/// Inputs

FilterBar

A wrapping row of filter chips above a grid or list; selects one value or many, with an optional mono eyebrow.

import { FilterBar } from "@protocore/pds";

View as Markdown

Basics

Default single mode keeps exactly one chip active. Pass bare strings as options and control the selection via value / onValueChange.

Filter services

Multiple selection

Set mode="multiple" to toggle any number of chips. Options can be { value, label } objects; the selection is a string[] driven by values / onValuesChange.

Status

Showing 2 statuses

Label & divider

Add a mono label eyebrow before the chip row, and divider for a hairline underneath — the blog-index / listing-header treatment.

Region

When to use it

Use a FilterBar to filter a collection — a card grid, a listing, a table — where the options are short facets worth showing all at once. It's built on Chip, so reach for a single Chip when you need one standalone toggle rather than a managed set. Use SegmentedControl when you're switching a *mode* (one of a few), not filtering: a segmented control always keeps one active and reads as a view switch, while a FilterBar can clear to 'none' and supports multi-select. When facets grow long or need grouping, graduate to a Select (single) or a checklist in a popover.

Usage

Use it directly above the collection it filters so the relationship is obvious.
Include an 'All' option in `single` mode so users can clear the filter.
Switch to `mode="multiple"` when facets are additive (status, tags, regions).
Keep chip labels short — they're facets, not sentences.

Don't

Don't use a FilterBar to pick a form value — that's a Select or RadioGroup.
Don't overflow the row with dozens of chips; move long facet sets into a Select.
Don't mix `single`-mode props (`value`) with `multiple`-mode props (`values`).
Don't use it to switch view modes — a SegmentedControl signals that better.

Accessibility

Keys	Action
`Tab`	Move focus to the next chip.
`Space / Enter`	Toggle the focused chip's selected state.

The bar is a `role="group"`; each chip is a real button reflecting its pressed state.
Selection is signalled by the inverted fill plus state, not colour alone.
Give the bar meaning with the `label` eyebrow or an ambient heading so the filter set is named.

`FilterBar` props

Prop	Type	Default	Description
`className`	`string`	—
`defaultValue`	`string`	—	Uncontrolled initial value.
`defaultValues`	`string[]`	—	Uncontrolled initial values.
`divider`	`boolean`	—	Draw a hairline under the bar. Default false.
`label`	`ReactNode`	—	Optional mono eyebrow rendered before the chip row.
`mode`	`enum`	—	Selection mode. `single` (default) keeps exactly one chip active. Selection mode. `multiple` toggles any number of chips.
`onValueChange`	`((value: string) => void)`	—	Fires with the newly selected value.
`onValuesChange`	`((values: string[]) => void)`	—	Fires with the next set of selected values.
`options` *	`FilterOption[]`	—	The filter options.
`style`	`CSSProperties`	—
`value`	`string`	—	Controlled selected value. Pair with `onValueChange`.
`values`	`string[]`	—	Controlled selected values. Pair with `onValuesChange`.