FilterBar

FilterBar helps users easily filter datasets using one or more filter criteria. A range of form elements can be added as filter controls.

OverviewPropertiesUsageAccessibility

New

Import

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

Demo

FilterBar is designed for filtering with multiple controls. This example shows a FilterBar with a TextInput, a single Select, a multi-select Select, and a TimeframeSelector. See Usage for best practices.

Give items unique names

The name provided to the FilterBar.Item must be unique to initialize the defaultValue correctly. This is true even if the item is rendered conditionally. If the same name is used for two items, React will map the name of the new item to the old defaultValue.

{conditionalFilter ? (
          <FilterBar.Item name="conditional-keyword" label="Keyword">
            <TextInput defaultValue='Automation' />
          </FilterBar.Item>
        ) : (
          <FilterBar.Item name="conditional-owner" label="Owner">
            <TextInput defaultValue="Dora Braun" />
          </FilterBar.Item>
        )}

Filter text

Use the SearchInput within the FilterBar for searching accross fields (e.g., multiple columns). Only one SearchInput should be used per FilterBar. Use the TextInput for targeted, text-based filtering (e.g., for one specific column). This allows users to narrow down results by entering keywords or phrases.

Reset filter values

This example shows how to reset filter item values in controlled scenarios. The FilterBar.ResetButton depends on an onClick hander to reset the filter values. Therefore, the reset button can only be used with controlled FilterBar components.

Prefill additional filters

If you know the most likely value for an additional, or secondary, filter, you can help users by setting it as the defaultValue.

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

To make the changed value persist, the value property should be used instead. In this way, the changed value is saved, even if the filter is removed. (The value is no longer considered for the filtering.)

Render filtered data in a table

Connect FilterBar with DataTable with the useFilteredData hook. To filter the data in the table, 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.

By default, the filter name must match the column name. If a custom filter logic is required, provide a filter function as the second argument. This example shows a custom filter function that searches for a match in every column of a row.

Persist sorting of filtered data

When using the useFilteredData hook to filter table data, the table must re-render each time the filteredData changes, which also resets the sorting. To keep the sorting, use the sortBy and onSortChange props along with enableDefaultSort.

Filter sub-row data

The useFilteredData hook can also handle filtering of table data with sub-rows.

By default, on the matching paths, the sibling rows are also displayed for easy comparison. In other words, when a child matches, other children at the same level are also included (on all levels of the matching path). Control this behavior using the subrowMatchingBehavior parameter, to include or exclude those sibling rows.

For nodes which match, all of their sub-rows are included irrespective of subrowMatchingBehavior.

The return value expandedRowIds provides all the IDs of ancestors of matching nodes. Feed those values to openSubRows of the DataTable to ensure matching nodes are visible.

Pin and unpin optional filters

Important filters should always be visible. However, you can allow users to hide uncommon, optional filters in the 'Add filter' dropdown. Pass the configuration object defaultPinnedState to the FilterBar to set filter states, as follows:

• pinned items are always visible and can't be unpinned or hidden by the user.

• pinned-optional items are visible initially, but the user can unpin and hide them in the dropdown.

• optional items aren't visible initially, but the user can access them from the dropdown and pin them. When a filter item is pinned, it's automatically focused.

Filter items that aren't configured will default to pinned.

Dropdown items use the text content of the label, stripping away all other content. Be sure to add an aria-label or name for each pinned-optional and optional filter, as these are required for the dropdown. If there's no text content, the aria-label or the name will be used as a fallback.

Control pinned state

To control the pinned state of filter items, pass the pinned state configuration to the pinnedState prop. To handle changes in the 'Add filter' dropdown, provide a callback to the onPinnedStateChange prop. The callback triggers whenever different items are selected, receiving the suggested pinned state and a list of item names.

Use custom component

To use a custom component as a FilterBar.Item, use the React forwardRef. 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.

• defaultValue if the component is uncontrolled. The ref is required to focus or open items from additional filters in the dropdown. This means that you must also use the imperative handle in your component to expose the ref of your input element.

  Be sure to add an aria-label or name for each custom component. If there's no text content, the aria-label or name will be used as a fallback.

Related

Patterns

Filtering