FilterBar

Use the FilterBar to filter a set of data based on one or several criteria determined by the user. The component allows you to add various form elements as filter controls.

OverviewPropertiesUsage

Import

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

Use cases

Filter text

To implement data filtering functionality, you can use a TextInput component in your code. This allows users to filter data by entering text.

CodeSandbox

Filter with multiple controls

This example shows how you can filter data according to several criteria at the same time. In this case, you can filter with a TextInput, a single SelectV2, a multiple SelectV2, as well as a TimeframeSelector.

CodeSandbox

Filter with a custom component

You can use any custom component inside as the FilterBar.Item. Use the React forwardRef to make it work. Forward the ref to the wrapper element and add the following contract props:

value - if the component is controlled; the onChange callback is also required for controlled components.

defaultValue - if the component is uncontrolled. The ref is necessary for focusing or opening an item that's added from additional filters in the dropdown field. This means that you also need to use the imperative handle in your component to expose the ref of your input element.

CodeSandbox

Reset filter values

This example shows how you can reset filter item values. Note that when using controlled items, you need to call the onFilterChange callback, as it's only called automatically in uncontrolled scenarios.

CodeSandbox

Filter with optional controls

Usually, filter controls are visible by default. However, the FilterBar allows you to add optional filters that are hidden behind a dropdown field. To define which items from the dropdown should be visible, optional, or hidden, a configuration object can be passed to the FilterBar. The configuration object (defaultPinnedState) consists of the filter item names and their pinned state (pinned, optional, or pinned-optional). If an item isn't included in the configuration, it will fall back to pinned.

If an item is pinned, it will always be shown and can't be removed.

If an item is optional, it won't be shown initially, but can be added and removed from the dropdown. When a filter item is added, it's automatically focused.

If an item is set to pinned-optional, it will be shown initially, but the pinned state can also be edited in the dropdown.

The items in the dropdown use the text content of the label and strip any other content. If there's no text content, either the aria-label or the name is used as a fallback.

CodeSandbox

Prefill additional filters

In some cases, a specific value is the most likely one of an additional filter. To help the user, it's also possible to set a defaultValue on the additional filter. However, this filter is still only applied once it's selected.

The user can overwrite the defaultValue, but if the filter is removed and reapplied, it will revert to the defaultValue.

If the changed value should persist, the value property should be used instead. In this way, the updated value is saved, even if the filter is removed. (The value is not considered for the filtering anymore.)

Apart from the client-side filtering, the FilterBar should represent a particular state of filtered data. For example, when generating special views that already apply some filters. To do so, the used filter values must be passed to the form control, either with value or defaultValue.

CodeSandbox

Filter with controlled pinned state

The pinned state of filter items can also be controlled by you. Therefore, the pinned state configuration must be passed to the pinnedState prop instead. To react to changes of the 'Add filter' dropdown a callback must be provided to the onPinnedStateChange prop. The callback is called as soon as different items are selected in the dropdown. The first param is the suggested pinned state and the second returns the names of all changes items.

CodeSandbox

Render filtered data inside a table

Use the useFilteredData hook to connect the FilterBar with the DataTable. To filter the data in the table, simply pass the unfiltered data as the first argument to the hook. The useFilteredData hook returns the filteredData that must be passed to the table's data prop along with the onChange handler which can be plugged into the onFilterChange callback.

For out of the box filtering, the filter name has to correspond to the column name. If you want to implement a custom filter function, you can provide one as a second argument. The following example provides a custom filter function that searches for a match in all columns of a row.

CodeSandbox

Persist sorting when filtering table data

When using the useFilterdData hook to filter table data, the table needs to rerender whenever the filteredData changes, which would also reset the sorting. To keep the sorting, you can use the sortBy and onSortChange props along with enableDefaultSort to store and apply the sorting even when the filter changes.

CodeSandbox

Filter server-side data

The FilterBar component can fetch filtered data from an external resource (server-side) if not all data is available on the front end to handle the filtering locally.

CodeSandbox

Filter with custom logic

You can also define custom filtering logic. This example shows how you can negate a text filter. So if the entry's full name does not match the text entered in the input, it's included in the result.

CodeSandbox

Caveats

The name provided to the FilterBar.Item must also be unique, even if items are rendered conditionally. For example:

{conditionalFilter ? (
          <FilterBar.Item name="conditional-text-company" label="Company">
            <TextInput defaultValue="Dynatrace" />
          </FilterBar.Item>
        ) : (
          <FilterBar.Item name="conditional-text-office" label="Office">
            <TextInput defaultValue="JKU" />
          </FilterBar.Item>
        )}

This is important for initializing the defaultValue correctly. If the same key is used, React maps the key of the new item to the old defaultValue and doesn't reinitialize it with its new defaultValue.