BlogCategoryFilter

Single-select tag filter for the blog archive: a labelled group of toggle chips with an implicit All, three visual treatments, optional per-tag counts and an optional collapsed mode.

Status: stable. Group: navigation. Markdown version: /design-system/components/blog-category-filter.md

When to use

Category filter control for the blog archive. Blog-scoped variant; for generic list pages use CategoryFilter.

When not to use

Do not use this for generic list pages; that is CategoryFilter.

Look-alikes

CategoryFilter: Do not use this for generic list pages; that is CategoryFilter.

Props

BlogCategoryFilter props
Prop	Type	Default	Description	Required
`tags`	`string[]`	none	Array of unique tags.	Yes
`selectedTag`	`string \| null`	none	Currently selected tag (null means "All")	Yes
`onTagChange`	`(tag: string \| null) => void`	none	Callback when tag selection changes.	Yes
`showCounts`	`boolean`	`false`	Show post counts per tag.	No
`tagCounts`	`Record<string, number>`	`{}`	Tag counts object.	No
`variant`	`"pills" \| "underline" \| "minimal"`	`pills`	Style variant.	No
`size`	`"sm" \| "md" \| "lg"`	`md`	Size variant.	No
`collapsible`	`boolean`	`false`	Collapse to the selected chip and a disclosure button; expanding shows every chip and picking one collapses back to it.	No
`className`	`string`	none	Custom className.	No

Variants

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

Invalid combinations

The contract records no invalid combinations.

Keyboard

BlogCategoryFilter keyboard behaviour
Key	Behaviour
Tab	Moves to and through the filter buttons.
Enter/Space	Or click activates the focused filter.
General	With collapsible, a disclosure button is the first child of the group; Enter/Space or click shows or hides the chips.

Rules

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

BlogCategoryFilter rules
Level	Rule	How it is checked
MUST	ARIA: Role=group labelled via blogFilterByTag; each filter is a toggle button with aria-pressed.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Single-select: exactly one filter has aria-pressed=true at a time (visual + aria-pressed convey the active filter)	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: With collapsible, the disclosure button carries aria-expanded (no aria-controls: it sits inside the group) and an aria-label from blogFilterAllTopics; its caret icon is aria-hidden.	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.
MUST NOT	Maintainers: Do not invent parallel primitives inside this folder.	Release review; not machine-checked.

Install and import

In-repo only. BlogCategoryFilter is not exported from @digitaltableteur/react, so there is no public import path.