React Components

# 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.

<table class="_table_e3iru_2 _table--md_e3iru_59 _table--striped_e3iru_167 _identity-card__table_75e8e_7" data-ods="table" data-storybook="table"><tbody><tr><th scope="row">Name</th><td>QueryFilter</td></tr><tr><th scope="row">Also known as</th><td>-</td></tr><tr><th scope="row">Links</th><td><a class="_link_1qra4_2 _identity-card__app-link_75e8e_12" data-ods="link" href="https://www.figma.com/design/9jDDTcR4a9jPRFcdjawAlf/ODS---UI-Kit?node-id=0-1&amp;p=f&amp;t=kwInPIiCg5eOsgBa-0" target="_blank">Design <span class="_icon_g76et_2 _icon--external-link_g76et_256" data-ods="icon" role="presentation"></span></a><a class="_link_1qra4_2 _identity-card__app-link_75e8e_12" data-ods="link" href="https://github.com/ovh/design-system/tree/master/packages/ods-react/src/components/query-filter" target="_blank">Github<span class="_icon_g76et_2 _icon--external-link_g76et_256" data-ods="icon" role="presentation"></span></a></td></tr></tbody></table>

## 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

---

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.".