Components

Search Filter

Use with caution: candidate

This component implements faceted search.

Examples

Default

View va-search-filter Default in Storybook

Active filters

View va-search-filter Active Filters in Storybook

Usage

Faceted search is a way to filter search results by using attributes, or facets, like color, price, or size. It’s also known as faceted browsing or faceted navigation. Filtering reduces the results returned by search facet. Filtering can help a user reduce search results to find things faster.

When there are facets to filter by and when there is more than one page of results. Filtering is not required but recommended in these scenarios:
- When there are categories of results (facets) returned AND
- Where there is more than 1 page of results (i.e results are not pre-determined to be limited to a short list of 10-20 items)

When to consider something else

Use a radio button when only one filter can be applied at a time. If a facet only allows mutually exclusive results at a time, in other words only one filter can be applied at one time, then you will need to roll your own version of filtering and use the Radio button component as the interaction input up to 5 items. For more than 5 items use a Select component.
Use a segmented button as an alternative when there are limited facet items. When there are only 2-3 items within a facet that can be filtered on, use of a Button - Segmented component is an option excluding task flows such as filling out a form, reviewing secure messages, etc.

Behavior

Filters collapse inside an Accordion below table width. At mobile viewports, up until the tablet breakpoint, filters should collapse inside an Accordion component.
Checkboxes allow for filtering on multiple facets. Multiple facet filtering uses the Checkbox component as the interaction input.
Filtering must have a distinct button to apply filtering to the results. This component uses a button component to apply filtering.
Filtering must provide a way to clear or reset all filters. The user must have a clear and easy way to clear or reset all filters. Thus the inclusion of the “Clear all filters” button

Placement

Refer to the search results template for placement.

Code usage

Attributes and Properties

Property Attribute Type Default Description

filterOptions FilterFacet[] [] Represents a list of filter facets and their categories. Use a JSON array of objects with label and id properties.

header header string 'Filters' The filter header text.

Events

Name Description

vaFilterApply A custom event emitted when the apply filters button is clicked.

vaFilterChange A custom event emitted when the filter changes. The payload will provide all active categories.

vaFilterClearAll A custom event emitted when the clear all filters button is clicked.

resize

Component checklist

Maturity

Guidance: Examples, usage, code usage, content considerations, and accessibility considerations are all complete.
Research: VFS team conducted research on this component which is linked from this page.
Stability: Component has been in production for more than 3 months with no significant issues found.
Adoption: Multiple teams have adopted this component.

Accessibility

While this component has been previously tested against older criteria, it has not yet been audited with the updated testing criteria.

Code assets

Variations: Storybook includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
Responsive: Component depicted in all responsive breakpoints.
Interactive states: Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
Tokens: All design attributes (color, typography, layout, etc.) are available as tokens.
Internationalization: Describes i18n attributes.

Visual assets

Variations: Figma library includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
Responsive: Component designed to work in all responsive breakpoints.
Interactive states: Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
Tokens: All design attributes (color, typography, layout, etc.) are available as tokens.

30% complete (4 of 13)

Legend:

Complete
Incomplete
Not applicable