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.
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.
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
.
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.
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.
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.
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
.
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.
Render filtered data inside a table
In this example, you can see how the filter bar can be combined with the table
to render filtered data. You can use our custom hook useFilteredData
to
connect the DataTable
data to the FilterBar
. The hook returns the onChange
handler that's necessary for the filter, as well as the filteredData
for the
DataTable
. The filter searches for a match in all columns of a row.
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.
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.
Caveats
The FilterBar can be used with the TimeframeSelector
. However, the onChange
only returns the value
and not the TimeframeSelectorDetails
. To display more
detailed information, use the following snippet:
const timeframeValue = filterValue as Timeframe;
const start = parseTime(timeframeValue.from)?.date;
const end = parseTime(timeframeValue.to)?.date;
The topic is currently being revisited and will be adapted for easier usage.
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
.
Props
FilterBarProps
Signature:
export declare type FilterBarProps = ( | ) & ;
FilterBar.Item
You can use the FilterBar.Item
component to render an item inside the
FilterBar
, as shown above.
FilterBarItemProps
,
Name | Type | Default | Description |
---|---|---|---|
name | - | A unique identifier for this sub-filter (must only be unique for this filter). In case custom labels are used without text children, this is displayed on the MoreMenu trigger instead. | |
label | - | Description text of this sub-filter. If you use a custom label without text children, the name will be displayed on the MoreMenu instead. | |
children | - | Only one element, is expected here. | |
defaultPinnedState? | | | | 'pinned' | Determines whether the filter is pinned, optional (hidden in the dropdown) or pinned and optional. |
showLabel? | - | Defines if the label is shown for the filter item. If set specifically, it also overwrites the general configuration set with the showLabels prop on the FilterBar for one item. |
FilterBar.ResetButton
You can use the FilterBar.ResetButton
component to render a button that resets
all filters, as shown above.
ResetButtonProps
, , ,
Name | Type | Default | Description |
---|---|---|---|
onClick | () => | - | Handler that is called when the ResetButton is clicked. |