FilterChip

Single-select filter toggle chip: a button[aria-pressed] with pill, rectangle, underline, and minimal treatments.

Status: stable. Group: form. Markdown version: /design-system/components/filter-chip.md

When to use

Use FilterChip inside a labelled single-select filter group when a compact option must expose its active state with aria-pressed. Keep one chip pressed and use count for result totals so the accessible name stays synchronized.

Use FilterChip to filter a visible collection such as a work grid or blog archive.

When not to use

Do not use for navigation between panels (that is Tabs).
Do not nest interactive content inside the label.
Do not use FilterChip as navigation between content panels; use Tabs.
Do not use FilterChip for multi-select token input; use MultiCombobox.

Look-alikes

MultiCombobox: Do not use FilterChip for multi-select token input; use MultiCombobox.
Tabs: Do not use FilterChip as navigation between content panels; use Tabs.

Props

FilterChip props
Prop	Type	Default	Description	Required
`pressed`	`boolean`	none	Whether this chip's filter is active (rendered as aria-pressed).	Yes
`children`	`React.ReactNode`	none	Chip label (compose counts etc. inline).	Yes
`variant`	`"underline" \| "minimal" \| "pill" \| "rectangle"`	`pill`	Visual treatment.	No
`size`	`"sm" \| "md" \| "lg"`	`md`	Size token.	No
`count`	`number`	none	Optional count suffix, rendered as "(n)".	No
`className`	`string`	none	Additional CSS class names.	No

Variants

Available variants: pill, rectangle, underline, minimal (default pill).
Available sizes: sm, md, lg (default md).

Invalid combinations

The contract records no invalid combinations.

Keyboard

FilterChip keyboard behaviour
Key	Behaviour
Tab	Moves focus to the control and on to the next focusable element. (standard)
Enter	Activates the focused control. (standard)
Space	Activates or toggles the focused control. (standard)

Rows marked (standard) name a key the contract lists without a description; the behaviour shown is the usual one for that key.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

FilterChip rules
Level	Rule	How it is checked
MUST	ARIA: Aria-pressed reflects the pressed prop (toggle button, not tab)	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Parents wrap chips in a labelled role=group.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	Required stories produce no axe violations at the configured severity.	Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8.
MUST	The accessibility tree (role, name, state) matches the committed snapshot for every required story.	Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2.
MUST	The component remains legible and operable under a real browser forced-colors: active pass.	Automated by `npm run test:stories:hc`.
MUST	Every documented keyboard interaction works as specified.	Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2.
MUST	A human completed an end-to-end accessibility review of this component.	Manual review, last on 2026-11-04.
SHOULD	Keep exactly one chip pressed in a single-select filter group.	Not stated in the contract.

Install and import

Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
Import: import { FilterChip } from "@digitaltableteur/react";
Entry point: @digitaltableteur/react/actions exports it too.
Styles: import @digitaltableteur/react/style.css once at the app boundary.
Also available as the custom element <dt-filter-chip>; see the custom elements manifest.