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

Customize comparison 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

Load suggestions async

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

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.

The supported replacement strategies are:

Strategy	Behavior
replace-token (default)	Replace the token at the cursor position.
replace-statement	Replace the whole statement at the cursor position.
replace-all	Replace the whole filter.
insert	Insert at the cursor position 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

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 the FilterField in a form

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.

Clearing the FilterField also triggers the onFilter callback.

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

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

Work with the syntax tree

The FilterField provides a tokenized version of the entered value, grouping statements that are connected with the same logical operator. With the logical AND having a higher precedence than the logical OR, the statements a = 1 b = 2 OR c = 3 will be grouped as follows:

CodeSandbox

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 and the accompanying isValid flag is set to false.

Explicit logical operator nodes

Explicit logical operators are included in the syntax tree so we can convert the tree back to a string without losing any information. The logical operator you need to use for evaluating a group of statements is already included on the Group node. Ignore logical operators in the children array of groups.

Convert string to syntax tree

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

Convert syntax tree to string

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

See the example below for converting from string to tree and back.

CodeSandbox