--- title: "Query Filter" slug: query-filter category: component type: documentation version: 20.0.0 tokens: 1358 source: https://ovh.github.io/design-system/v20.0.0/llms/react-components-query-filter--documentation.txt --- # Query Filter ## Overview The **Query Filter** component allows users to find specific items within a collection by constructing queries based on properties and property values. Users can combine structured property conditions with free-text search to create precise filters without writing raw query syntax. | | | |---|---| | Name | QueryFilter | | Design | https://www.figma.com/design/9jDDTcR4a9jPRFcdjawAlf/ODS---UI-Kit?node-id=0-1&p=f&t=kwInPIiCg5eOsgBa-0 | | Source | https://github.com/ovh/design-system/tree/master/packages/ods-react/src/components/query-filter | ## Usage The **Query Filter** is typically used as a toolbar or input control above data tables or card grids to help users quickly narrow down large datasets. It is commonly used in: - Dashboards and admin interfaces. - Productivity tools with lists or tables of items. - Applications where filtering and search are core workflows. ### Dos & Don'ts **Do** - Use Query Filter to enable multi-property search and filtering - Apply the Query Filter to the full dataset, not just currently visible or loaded items - Keep the query readable by ordering tokens logically and avoiding unnecessary duplication of conditions **Don't** - Don't rely on Query Filter for very small collections where scanning the list is faster - Don't use property tokens for datasets dominated by long free-form text - Don't use operators that don't match the property type (e.g., "between" for single-value properties) ### Best Practices in Context 1. **QueryFilter** 2. **Filter input** 3. **Suggestions panel** 4. **Token** 5. **Clear all filters button** ## Placement The **Query Filter** component is typically positioned above the target data container. ## Behavior ### Opening & Closing Clicking the filter input opens the suggestions panel. The panel closes when: - A value is selected. - Clicking outside the component. - The `Escape` key is pressed. ### Adding a Filter Suggestions guide the user through: - Property selection - Operator selection - Value entry Free-text is allowed and creates a distinct token. ### Removing a token Each token can be removed by click. Backspace behavior does not remove last token unless specifically focused on it. Optional "Clear all filters" button removes all tokens in one action. ## Navigation ### Focus Management Focus follows a logical order from left to right. When the suggestions panel is open, focus moves within the panel without leaving the component. ### General Keyboard Shortcuts Pressing `Tab` moves focus between the input field, and other interactive elements. Pressing `Arrow Down` opens the suggestions panel and moves focus to the first suggestion. Pressing `Escape` closes the suggestions panel. Pressing `Backspace` deletes characters in the input field ## Accessibility ### Always provide an explicit label Every **Query Filter** must have a clear and explicit label to ensure that users (especially screen reader users) understand its purpose, using either **FormField** or a native label tag. ```tsx { const filterProperty = useMemo(() => ({ label: 'Properties', options: [{ label: 'States', value: 'states' }], }), []); const filterOption = useMemo(() => ({ states: { operator: { label: 'Operators', options: [{ label: 'equals', value: '=' }], }, value: { label: 'State Values', options: [ { label: 'Running', value: 'running' }, { label: 'Stopped', value: 'stopped' }, ], }, }, }), []); return ( Filter instances: ); } ``` Screen readers will announce the label, the field and its content. When the design has no visible label, for example in a toolbar above a table, pass an `aria-label` to the **QueryFilterControl**: it is applied to the field itself. ```tsx { const filterProperty = useMemo(() => ({ label: 'Properties', options: [{ label: 'States', value: 'states' }], }), []); const filterOption = useMemo(() => ({ states: { operator: { label: 'Operators', options: [{ label: 'equals', value: '=' }], }, value: { label: 'State Values', options: [ { label: 'Running', value: 'running' }, { label: 'Stopped', value: 'stopped' }, ], }, }, }), []); return ( ); } ``` Screen readers will announce the label, the field and its content. ### Announce filter changes Use ARIA (Accessible Rich Internet Applications) live regions to announce filtering changes. For example: - When a filter is added: `aria-live` region could say "Filter 'Status: Active' has been applied.". - When a filter is removed: `aria-live` region could say "Filter 'Status: Active' has been removed.".