Filter
A group of toggleable pill or outline buttons for filtering content by category
Category: inputs · WCAG 2.2-AA · filter, chip, tag, pill, facet, category
Variants
- pill
- outline
States
- default
- selected
- hover
- focus
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. |
ariaLabel | string | — | Invisible accessible name. The catalog convention; the DOM spelling `aria-label` is accepted as an alias so either guess compiles. |
aria-label | string | — | Accessible label for the filter group. |
options | FilterOption[] | — | Array of { label, value } objects to render as filter buttons |
value | string[] | — | Controlled selected values |
defaultValue | string[] | [] | Initial selected values for uncontrolled use |
onValueChange | (selected: string[]) => void | — | Called with the selected values whenever the selection changes. |
multi | boolean | false | Allow multiple items to be selected simultaneously |
variant | 'pill' | 'outline' | pill | `pill` fills the selected chip with the accent colour; `outline` marks it with an accent border and text instead, leaving the fill transparent. |
multiple | boolean | — | Alias of `multi` — the HTML spelling (`<select multiple>`), accepted because it is the guess an adopter makes first. `multi` stays canonical. |
Design tokens
--cascivo-color-accent-text--cascivo-radius-full--cascivo-border-default--cascivo-color-text-subtle--cascivo-color-text--cascivo-color-active-bg--cascivo-color-accent--cascivo-color-accent-content--cascivo-ring-width--cascivo-ring-color--cascivo-ease-out
When to use
- Tag or category filtering on listing pages where the active filters must remain visible
- Facet chips that toggle content visibility (e.g. product categories, team labels)
When not to use
- Navigation between distinct views — use Tabs
- A binary on/off switch — use Toggle
- Form field for selecting a value — use Select or Checkbox
How to build an accessible Filter in React →
Examples
Single-select
<Filter
options={[
{ label: 'All', value: 'all' },
{ label: 'Active', value: 'active' },
{ label: 'Archived', value: 'archived' },
]}
aria-label="Filter by status"
/>Multi-select
<Filter
multi
options={[
{ label: 'Design', value: 'design' },
{ label: 'Engineering', value: 'engineering' },
{ label: 'Marketing', value: 'marketing' },
]}
aria-label="Filter by team"
/>Outline variant
<Filter
variant="outline"
options={[{ label: 'React', value: 'react' }, { label: 'Vue', value: 'vue' }]}
aria-label="Filter by framework"
/>