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

When to use

The FilterField serves as the primary means for users to filter content in your app.

• Use the FilterField for complex filter statements.
• Use the FilterField if your users need support for AND and OR connections between filters.
• Use the FilterField if your users need support for complex comparators, like excluding values or checking whether a value exists, or partial matches, like starts with, ends with, and contains.

There are a variety of other components that allow users to filter content in your app. Most notably, the FilterBar, the TimeframeSelector, and other form components. Carefully consider what users need to filter for and then decide on a component that best fits your use case.

For simple filter statements, use the FilterBar. Don't use combinations of the FilterField and the FilterBar.

Integration

When you integrate the FilterField in your app, make sure you

• don't deviate from the Dynatrace Documentation,
• don't alter the syntax,
• don't change the core behavior of the FilterField component.

Filter for timeframes

The TimeframeSelector allows users to quickly and conveniently set a timeframe. Always place the TimeframeSelector to the right, directly next to the FilterField.

Don't use the FilterField to allow users to set timeframes.

Where to use

Place the FilterField directly above the filterable content so users can establish a clear connection between the FilterField and the content it's affecting. Usually, the FilterField is above a DataTable, list, or grid that users can filter.

When to apply changes

You can react to changes in the FilterField as soon as the user starts typing. Don't filter content as long as users are writing invalid syntax. Be aware that prematurely updating content might frustrate users.

If you want users to deliberately and explicitly apply their changes, place a dedicated button next to the FilterField. This method also allows you to further reduce the number of times you have to update content.

When you place a dedicated button next to the FilterField, ensure to differentiate between filter statements that users still need to apply (2) and refreshing filter statements that users have already applied (3).

Logical operators

Filter statements are connected by either AND or OR operators. AND is the default operator. If no logical operator is specified between two filter statements, the system will automatically use the AND operator. To connect two filter statements with the OR operator, you must type OR between them.

Logical operator suggestions

Never suggest an AND operator or insert it automatically between two filter statements. Suggest the OR operator simultaneously with available keys to start a new filter statement. The OR is at the end of the suggestion list.

Order of key and value suggestions

Order key and value suggestions according to the following criteria:

Initial ordering (before user starts typing)

• For key suggestions:
  • If you provide 10 or fewer key suggestions, order them by relevance. The relevance can be determined using metrics (for example, how frequently a key is used in an app) or sensible defaults.
  • If you provide more than 10 key suggestions, order the first 10 keys by relevance and the rest alphabetically.
  • If the relevance of keys can't be determined, order all alphabetically.
• For value suggestions:
  • Order all suggestions alphabetically.

Dynamic ordering (as users type)

Once users start typing, narrow down the key and value suggestions relevant to the users' input. Prioritize the suggestions in this order:

1. Exact matches
2. Starts-with matches
3. Contains and ends-with matches

Within each prioritized group, keep the initial order.

When to group suggestions

The FilterField component allows you to group suggestions. However, you should only use the grouping feature if seeing the underlying structure will help users make a choice more quickly. Unnecessary grouping will only clutter the user interface and take away valuable screen space.