FilterField

FilterField is an advanced, text-based filtering component. It supports complex data filtering with intuitive filter field syntax and auto-suggestions.

OverviewPropertiesUsage

When to use

• When users need to filter large, complex datasets with many data points.
• When users need advanced filtering features. For example:
  • AND and OR operators between filters
  • Complex comparison operators for excluding values or checking whether a value exists
  • To find partial matches using starts-with, contains, or ends-with

A FilterField in combination with other filter components above a table.

When not to use

• For simple filtering where users don't need to control logical or comparison operators themselves. For these scenarios, use the FilterBar.
• Never combine FilterField and FilterBar for the same dataset.

For best practices on when to use which filter component, see Filtering.

Don't combine the FilterField and the FilterBar for the same dataset.

Position

• Always place the FilterField above the content it influences.
• Place the FilterField as close as possible to the content it filters, but ensure that its position follows the information hierarchy of your page.

Place the FilterField above and close to the content it influences.

General considerations

Consistency

• Never alter the implementation, features, behavior, or syntax described in the user-facing Filter field documentation. The FilterField component includes a direct link to it in the footer. Any inconsistencies will confuse or frustrate users looking for guidance.

Every FilterField includes a link to the user-facing FilterField documentation.

Performance

• Debounce your callback logic. Wait at least 300ms after the user stops typing before sending requests for suggestions.
• Use caching for previously loaded suggestions so you don't fetch them again.
• Limit the payload size that you get from the backend and that you send to the FilterField.
• Cancel outdated requests. For example, use AbortController.
• Keep the input responsive and avoid blocking the UI when network responses are slow.
• Don't fetch data on every keystroke without debounce.
• Avoid running complex logic synchronously in the suggestion callback.

Validation

Validation helps users understand if their input is formulated correctly to provide meaningful results. Follow our best practices for the main types of validation:

Syntax validation

Syntax validation shows users whether their input has the correct syntax. It's handled automatically by FilterField.

• Always wrap the FilterField in a FormField with a FormFieldMessages context to display validation messages in an accessible way below the FilterField.

Contextual validation

Contextual validation shows users if the keys, comparison operators, and values they used are meaningful in the given context.

• Use the validatorMap property to define specific valid keys, comparison operators, and values (e.g., error, info, warning) or general value types (e.g., string, number). Read more about the validatorMap property under Validate user input.
• Show custom error messages, such as backend timeouts or permission issues.

Logical operators

The FilterField supports the logical operators AND and OR. If users don't specify an operator, filter statements are automatically connected by an implicit AND, which is the default operator.

To connect two filter statements with the OR operator, users must enter OR between them.

• Never explicitly add AND operators in the FilterField unless users enter them.
• Never automatically add OR operators in the FilterField. Users must explicitly enter them.
• Avoid automatically connecting multiple values of the same key with an OR operator. Use the in () syntax instead.

Refer to rules for logical operator suggestions for guidance on when and where to suggest logical operators in the overlay.

Suggestions

Suggestions help users build valid filter expressions and discover available options. When the FilterField is focused, suggestions appear in an overlay below the field and update dynamically as the user types.

Show different suggestions in the FilterField depending on the user's input and the current suggestion type.

The FilterField suggestions are shown in an overlay and react to user input.

General rules

• Match the suggestion label to what will be inserted in the input, except for characters that require escaping. For example:
  • Don't use Warning as a suggestion label when the value WARN will be inserted.
  • Display Process group as the label, and insert "Process group" into the input.
• Only show matching suggestions when users start typing.
• Make matches case-insensitive and show them that way. For example, typing "cluster" also shows "Cluster" as a suggestion.
• Order key and value suggestions from most relevant to least relevant.
  • Define relevance based on your app's domain. This may include usage metrics (for example, how frequently a value is used in an app) or domain-specific defaults.
  • If the relevance can be determined for only some suggestions, list those first, and then order the others alphabetically below.
  • If the relevance can't be determined, use alphabetical order.
• Rank the matching suggestions in the following order when users start typing: exact matches, starts-with matches, contains and ends with matches. Within each ranking category, keep the original suggestion order (by relevance or alphabetically).
• Don't override FilterField's automatic suggestions, such as recently used, pinned, and search. These are managed by the component and triggered automatically based on the input phase, configuration, prioritization, and order.
• Don't include escape characters (" and \) in the suggestion unless part of the actual key or value. These characters are added automatically in the input field when the suggestion is selected.
• Don't hide or limit suggestions based on previous or subsequent filter statements.
  • For example, even if status = error is applied, still suggest status as a key.

Recommendation: Use description labels to clarify suggestions when labels are ambiguous or not self-explanatory.

Rules for key suggestions

Note

When using validatorMap, autoSuggestions={true}, or default onSuggest, key suggestions are automatically managed by the FilterField component.

Keys are filterable attributes or fields in a dataset that users can select to define their filter criteria. For example, Status.

• Always show key suggestions at the beginning of a new filter statement, for example, when the FilterField is empty or a complete filter statement is already present.
• Indicate the data type with an icon.

Key suggestions include an icon that indicates the data type.

Rules for filter statement suggestions (optional)

While users are typing, you can suggest the typed input as a value for a filter statement. This is common for two use cases:

• When the typed input matches a known filter value. For example, when a user types error, you suggest status = error.
• When suggesting the typed input as the value for commonly used keys. For example, when a user filters a list of entities and types dev, you suggest Entity name = dev.

If you include filter statement suggestions, follow these rules:

• Place filter statement suggestions below key suggestions.
• Suggest full filter statements consisting of key, comparison operator, and typed value.
• Suggest filter statements with matching values above the ones for commonly used keys.

Filter statement suggestions are shown for matching filter values and commonly used keys.

Rules for comparison operator suggestions

Note

With validatorMap or default onSuggest, operator suggestions are automatically managed by the FilterField component.

Comparison operators define how a key compares to a value. For example, equals = or does not equal !=.

• Always show comparison operator suggestions after users select a key suggestion or enter a space.
• Keep the default order of comparison operator suggestions unless the first suggestion won't lead to useful results for the given key.
• Only suggest comparison operators that are compatible with the key's data type.
• Don't auto-insert a comparison operator after a key.

Only suggest comparison operators that are supported for the entered key.

Rules for value suggestions

Note

With validatorMap, autoSuggestions={true}, or default onSuggest, value suggestions are automatically managed by the FilterField component.

Values are data that define a given key. For example, Warning and Error are potential values for a Status key.

• Always show value suggestions after users select a comparison operator suggestion or enter a space. The only exceptions are when:
  • The comparison operator is starts with, ends with, contains, exists, or matches phrase.
  • The value is a duration or number. In these cases, only show suggestions if they're truly helpful for users.

After a comparison operator has been selected, suggested values for the entered key appear.

Rules for logical operator suggestions

Note

With autoSuggestions={true} or default onSuggest, logical operator suggestions are automatically managed by the FilterField component.

Logical operators connect multiple filter statements. The FilterField automatically uses an implicit AND between two filter statements. The OR suggestion in the overlay helps users discover the second logical operator option.

• Always suggest OR once a statement is complete, and place it below the key and statement suggestions.
• Never suggest the AND operator, as it is implicit and handled automatically.

Show the OR suggestion below the key suggestions and don't include a suggestion for the AND operator.

Suggestion groups​

• If needed, use groups to categorize key and value suggestions within their suggestion type.
• Don't use generic group titles like "Key suggestions." Use categories that help users make a choice more quickly.

Apply filters

Users can apply filters to a dataset by triggering a dedicated button or using a keyboard shortcut.

• Filter values must be case-insensitive, while keys must be case-sensitive. For example, Status = Open and Status = open should return the same results, while Status and status are treated as different keys.
• When "Clear all" is used, wait for a confirmation before applying filter changes. For example, the user selects the "Apply" button or presses Cmd+Enter on macOS, or Ctrl+Enter on Windows/Linux.
• Never apply filters automatically while users are typing. Wait for an explicit user action instead.

Apply button

• Always provide a dedicated button near the FilterField to apply filters to the dataset.
• Use different button colors and variants to indicate if a filter has changed or is already applied:
  • If the FilterField is empty, or the filters have already been applied, use a neutral-colored, emphasized button.
  • If the filters have changed but haven't been applied yet, use a primary-colored, accent button.
• Include a ProgressCircle in the Button.Prefix and change the button label to "Cancel" while changes are being applied or the data is refreshing.
  • See Loading and saving behavior for guidance on when and for how long to show a loading indicator.
• Always keep the button clickable. Never disable it.

Example of a button near the FilterField that refreshes the dataset (1, 4), reacts to filter changes (2), and allows cancellation when something is loading (3).

Keyboard shortcuts

• Trigger the refresh or apply action when users press Cmd+Enter on macOS and Ctrl+Enter on Windows/Linux while interacting with the FilterField. Find more details in the Use the FilterField in a form documentation.
• Trigger the filter submission when users press Enter while the FilterField input is focused.