Components
Search Filter
Use with caution: candidateExamples
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 to use search filters
- 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
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
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
Note: This category is dependent on how you use this component. Test this for accessibility in your project.
-
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.
Legend:
-
Complete -
Incomplete -
Not applicable