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

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. The onSuggest callback provides all the information you need to determine which suggestions to show.

CodeSandbox

Enable matches phrase (~)

To enable support for the matches phrase comparison operators (~ and !~), you have to provide a validatorMap that explicitly lists matches-phrase or not-matches-phrase in the list of allowed operators. You can enable comparison operators globally (for all keys) or individually per key. The matches phrase comparison operators are compatible with keys that are of type Any, String, or any other type if you explicitly list it as an allowed operator for a key.

For details on mapping matches-phrase and not-matches-phrase to a DQL command and when to use which comparison operator, please visit the Dynatrace Documentation.

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 learn more about the syntax refer to the Dynatrace Documentation. 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. Use the FilterField.SuggestionGroupLabel to add a label to the group.

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 doesn't trigger the onChange callback. 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

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

Validate user input

To validate user input, you can set restrictions for keys, comparison operators, and values via the validatorMap property. Depending on how you configure the validatorMap, the FilterField highlights errors and shows appropriate suggestions in the FilterField.Suggestions (provided the autoSuggestions property of the FilterField is set to true).

CodeSandbox

Define keys

You can define a list of keys in the validatorMap property that is interpreted as valid. For any keys that are not in that list, the FilterField will show an error. By setting the exhaustive property of validatorMap to false, users can enter any key without triggering an error.

CodeSandbox

Define types for keys

You can set one or multiple types for any given key in the FilterField which restricts the list of comparison operators and values a key accepts. This is done by providing a type to the valuePredicate for keys listed in the validatorMap property. Types are set per key and can't be set globally for all keys.

To overwrite type restrictions of comparison operators, you can explicitly set allowed comparison operators for a key.

CodeSandbox

Available types and their comparison operators are:

Type	Comparison operators
Any	equals, not-equals, less-than, less-or-equal, greater-than, greater-or-equal, in, not in, exists, not-exists
Boolean	equals, not-equals, exists, not-exists
Duration	equals, not-equals, less-than, less-or-equal, greater-than, greater-or-equal, in, not in, exists, not-exists
Number	equals, not-equals, less-than, less-or-equal, greater-than, greater-or-equal, in, not in, exists, not-exists
String	equals, not-equals, in, not in, exists, not-exists, starts-with, not-starts-with, ends-with, not-ends-with, contains, not-contains

Define values for keys

For any given key in the validatorMap property, you can define a list of values that is interpreted as valid. This is done by passing an array to valuePredicate. For any values not in that list, the FilterField will show an error.

If, additionally to a list of values, you pass key types as a valuePredicate, the FilterField will accept any values of that list and any values of that type.

CodeSandbox

Alternatively, if you need to validate values according to a certain logic, you can pass a validator function to valuePredicate which allows you to write a custom error message in case of an error. Use this, for example, to check whether a value follows a special pattern.

Make sure to only pass pure or cached functions and avoid calling convertStringToFilterFieldTree in combination with a validatorMap inside of the validator function, as this may cause infinite loops.

CodeSandbox

Define comparison operators

The validatorMap property lets you define a list of comparison operators which can be done globally (for all keys) or individually per key. For any comparison operator that is not defined in those lists, the FilterField will show an error.

If you define comparison operators globally, be aware that key types may also already narrow down the list of allowed comparison operators. If you define comparison operators specifically for a key, they will overwrite restrictions set by the type of the key.

CodeSandbox