Skip to main content

FilterField

The FilterField component is a text-based input component that allows users to enter filters using an intuitive and easily understandable syntax. Since the input is text-based, users can always enter anything they want. To provide guidance to the user, we recommend always using the FilterField in combination with suggestions.

Experimental

The FilterField is still experimental. Be aware that the API is subject to change.

OverviewPropertiesUsage

Import​

import { FilterField } from '@dynatrace/strato-components-preview/filters';

Use cases​

Filter for simple key-value pairs​

Use the FilterField.Suggestions and FilterField.Suggestion components to provide suggestions to the user. The onSuggest callback provides all the information you need to determine which suggestions to show.

CodeSandbox

Load suggestions async​

Load suggestions async and display the suggestions overlay in a loading state by setting the loading prop on FilterField.Suggestions.

CodeSandbox

Change syntax to basic mode​

Set the syntax prop to basic to narrow down the set of rules used to parse the input. In the basic mode, logical or and grouping are not supported. All filter expressions are automatically connected with and.

CodeSandbox

Submit filters​

The user can submit the FilterField using Enter or Ctrl / Cmd + Enter. This triggers the onFilter callback, which provides the string representation of the value, the syntax tree, and its validity state.

CodeSandbox

Use the FilterField in a form​

The FilterField can be submitted with a form and by default shows a set of error messages based on the entered value, rendered as tooltips. Use the FormField to make the error state more present and add an accessible error message underneath the FilterField. Read up on how to use the FormField here.

CodeSandbox

Customize operator suggestions​

With the autoSuggestions prop set to true, relevant operator suggestions are automatically added to the list of suggestions. You can customize those by omitting autoSuggestions and using the returned autoSuggestions in the onSuggest callback.

CodeSandbox

Group suggestions and add additional information​

Use the FilterField.SuggestionGroup to visually separate suggestions with a separator. The FilterField.SuggestionGroupLabel can be used to add a label to the group.

CodeSandbox

Use different strategies for inserting suggestions​

Using a pre-defined syntax, the FilterField parses the input and transforms it into tokens. A token represents a filter key, value, comparison operator, or logical operator.

By default, applying a suggestion replaces the token the cursor is currently positioned in with the suggestion's value. Use the insertionStrategy prop to alter the behavior. If the strategy is set to replace-statement, the statement the cursor is currently positioned in will be replaced, replace-all replaces the entire value of the FilterField and insert only inserts the suggestion without any replacements.

CodeSandbox

Escape suggestions​

The FilterField syntax uses the space as delimiter between keys, operators, values, and statements. To avoid an invalid syntax when applying a suggestion, you can use the value prop and the children of the FilterField.Suggestion component. The value is used when applying the suggestion, whereas the children are used to render the suggestion in the overlay.

In general, the following characters need to be escaped, either wrapping the whole value in double quotes, or using a \ to escape single characters:

  • * (Asterisk)
  • (Space)
  • ,
  • =
  • >
  • <

With the suggestion insertion strategy set to replace-token, the applied value is escaped automatically if need be.

Examples (the same examples are valid for keys as well):

  • Exact match of comparison operator
    • foo = \=
    • foo = \<
    • foo = ">"
    • foo = "!="
  • Starts with / ends with operator in value
    • foo = *"ba*r" (ends with ba*r)
    • foo = ba\*r* (starts with ba*r)
    • foo = *"ba*r"* (contains ba*r)
  • Space in value
    • foo = "b a r"
    • foo = b\ ar

Convert string to syntax tree​

Use the convertStringToFilterFieldTree utility to convert a string into a FilterTree. Setting the value from the outside does not trigger the onChange callback. In order to get the converted syntax tree and filter data accordingly, use the provided utility function.

CodeSandbox

Convert syntax tree to string​

Use the convertFilterFieldTreeToString utility to convert a syntax tree into a string.

CodeSandbox

Work with the syntax tree​

Note

The structure of the syntax tree is subject to change. Instead of a flat list of statements and logical operators, the statements will likely already be provided grouped under the relevant operators.

The FilterField provides a tokenized version of the entered value, grouping statements that are connected with the same logical operator. Each statement is represented by a node holding the key, operator, and value of the statement, provided as properties of the statement node. Depending on the type of value and operators used, additional information (e.g. starts-with, contains) is provided in the syntax tree.

If there is an error in the syntax, a node with type Error is included in the syntax tree.

Still have questions?
Find answers in the Dynatrace Community