Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

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 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

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

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.
70% complete (14 of 20)

Legend:

  • Complete
  • Incomplete
  • Not applicable
Edit this page in GitHub (Permissions required)
Last updated: Jun 03, 2025