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. When you filter results, you’ll narrow down what’s shown based on specific facets. This helps users find what they’re looking for 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 (meaning only one filter can be applied at a time), you’ll need to create your own version of filtering. Use the Radio button component as the interaction input for up to 5 items. For more than 5 items, use a Select component.
Use a segmented button as an alternative for limited facet items. When you have only 2-3 items within a facet that can be filtered on, consider using a Button - Segmented component. This doesn’t apply to task flows like filling out forms or reviewing secure messages.

Behavior

Filters collapse inside an Accordion below tablet width. In a mobile viewport, filters will collapse inside an Accordion component until you reach the tablet breakpoint.
Checkboxes allow for filtering on multiple facets. Use the Checkbox component as the interaction input for multiple facet filtering.
Filtering must have a distinct button to apply filtering to the results. We use a button component to apply filtering.
Filtering must provide a way to clear or reset all filters. Users need a clear and easy way to reset all filters. That’s why we include the “Clear all filters” button.

Placement

Mobile viewport widths: Place search filters below the search input component and above the sort component.
Desktop viewport widths: Place search filters in the left-side rail, below a full-width search input component.
Refer to the search results template. Check out the search results template examples for precise 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

For more information on each category, see Accessibility testing for design system components.

Last audit date: 2025-05-21

Code review: Pass

Readability: Conditional Pass

Automated scans: Pass

Use of color: Pass

Text resizing, zoom, and magnification: Pass

Screen readers: Pass

Input and interaction methods: Pass

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.

70% complete (14 of 20)

Legend:

Complete
Incomplete
Not applicable