The Filter Bar is used to apply and display filters to a data set. It is most often used in conjunction with the Advanced Table, but is flexible enough to support different data sets and rendering methods such as in a list or grid of cards.

The Filter Bar comes paired with a complex dropdown menu that displays available filter parameters (a parameter is often the equivalent of a column in a table), values within each parameter, support for numerical/date/time values, ranges of values, and actions to apply and clear filters from the data set.

Usage

When to use

• When displaying relevant filters and filters that have been applied to a data set.
• For common filter methods like multi-selection, single selection, numbers, dates, and times.
• As a direct replacement for the HDS Filter patterns guidance.

When not to use

• For complex query builder features.

Overlap with the Filter patterns guidance

The Filter Bar component is a successor to the Filter patterns guidance and supports the vast majority of filtering experiences within HashiCorp applications out of the box. New experiences should use the Filter Bar by default instead of the adhering to the pattern guidance, while already delivered features should consider migrating to the Filter Bar component.

Type

The Filter Bar supports two visual presentations, attached and standalone, to be used in different contexts and with different types of data sets.

Attached

Use the attached variant with the Advanced Table and standard Table.

Standalone

Use the standalone variant when a data set is rendered in formats other than a table, e.g., a list or array of cards.

Expand & collapse

The Filter Bar supports expanding and collapsing the applied filters section to help simplify the UI around the data set and bring focus to the data or content. This is especially helpful when many filters are applied or the data set is very complex.

When no filters are applied, the Filter Bar is collapsed by default and displays an empty state message when expanded.

When one or more filters are applied the Filter Bar is expanded by default.

Search

Use the search input in the Filter Bar to apply a broad text/string-based filter across the entire data set.

Bulk actions

The Filter Bar supports bulk actions corresponding with our recommendations for multi-select within a table, and can be used to perform actions across multiple results such as edit, delete, and different selection methods across the data set.

Generic content

If custom functionality is needed for manipulating the view or contents of the data set, a generic block is grouped with the bulk actions in the Filter Bar. We aren't prescriptive about what can be passed to this generic block, but it should generally be limited to additional actions (as Buttons) and Dropdowns with multiple grouped actions.

Applied filters

Applied filters are represented by a Tag displaying the filter parameter (the category or column the filter corresponds to) and the filter value (corresponding with the specific cell content).

The text rendered within the Tag uses a standardized format depending on the type of filter and the method:

• Single and multiple selection filters group the parameter and value using a colon; e.g., "Region: AWS (us-east)".
• Numerical filters group the parameter and value with an operator symbol; e.g., "Modules > 50".
• Date and time filters group the parameter and value with natural language; e.g., "Creation time before 12:00 PM".

For a full list of supported operators visit the specifications page.

Text within the Tag component will truncate at roughly 20 characters, about which more details can be found in the Tag documentation.

Custom applied filter text

If necessary, the default formatting within the Tag can be overidden with custom text. This can be useful if the label of the parameter is an irregular plural, if the parameter reads more naturally with certain punctuation or grammar, or for product-specific reasons.

Filter dropdown

The Filter Dropdown is responsible for the selection and application of filters and is broken two "panels":

• The left panel displays the list of parameters (categories) that can be filtered upon.
• The right panel conditionally displays either a list of options, or a grouping of input fields when filtering by a numerical, date, or time value.

Which filtering method to use depends on the data type and context. In the Figma component, select the type from the nested FilterValue component. In Ember, pass the filter type and method into the configuration.

Multi-selection

Multi-selection supports the selection of multiple values in a list of options and is the most common method of filtering. It is suited for categorical data like statuses and IDs, but can also be used more generally to filter by a handful of similar values.

Single-selection

Single selection supports a mutually exclusive selection using radio buttons; e.g., the selection of a value where more than one selection will logically result in an empty state, therefore, only value can be selected.

Numbers, dates, times, and datetimes

Filtering by numerical values, dates, times, and datetimes is handled through the combination of an operator (greater than, less than, before, etc.) and an input field or grouping of input fields. This filtering method is best suited for range-based filtering; e.g., filtering by results relationally compared to the value or range of values.

For a full list of supported operators visit the specifications page.

Custom filtering

If your filtering requirements extend beyond the methods supported directly by the component, the Filter Dropdown supports passing HDS components and custom elements to the values panel.

Search across filter values

Use the integrated search (hasSearch) in the values panel to allow users to search by string across all values within a selected parameter. While only relevant for single/multi selection, search can be useful if there are many filter values or if a unique naming convention is used to artificially group results together.

Applying Filters

Depending on how consumers would prefer to trigger the filtering on their data sets, the Filter Bar supports different methods of applying filters:

• Per-filter: selected filters are applied when the user confirms their selection with the "Apply filters" submit button in the Filters Dropdown. This is the most common method and generally requires a database or API call to update the data set with the corresponding filter parameters.
• Live filtering: filters are applied immediately upon selection. This method generally requires updating the data set on the client.

Clearing filters

Filters can be cleared either in bulk or individually from the Filter Bar or Dropdown.

Filter Bar

Clear all filters with the Button in the Filter Bar.

Clear filters individually via the dismiss button of the Tag.

Filter Dropdown

Clear all filters via the Button in the footer of the Dropdown.

Deselect all filter values within a parameter with the "Clear selection" Button, then confirm the changes with the "Apply filters" Button in the footer.

Clear filter input fields with the "Clear filter" Button, then apply the changes with the "Apply filters" Button in the footer.

How to use this component

The Filter Bar component is used to apply and display filters to a data set. The component does not handle any filtering of the data itself, but provides a way for a user to apply filters, and a means for displaying any filters that have been applied.

To use this component, set the filter options available for a data set using the Dropdown and FilterGroup contextual components. When filters are applied, the @onFilter callback provides a data object of the applied filters. To show which filters have been applied, pass a data object of the same structure to the @filters argument.

The Filter Bar is also available as a contextual component of the Advanced Table.