Filter bar
The bar above a list: the controls that narrow it, the filters in force as removable chips, “Clear filters”, and the count of results — the state kept by the app, in the address.
Web only — React, from @krizaka/ui/filter-bar. Beta: its API may still change in a minor version.
When to use
- Above a table or a grid people narrow with several criteria at once: status, type, owner, period, a query.
- When the filters must be visible and undoable one by one, and shared in a link.
When not to use
- For one choice among a few views of a list: chips in a single group.Use instead: Chip
- For a search alone: a search field.Use instead: Search field
Installation
Install
npm install @krizaka/ui @krizaka/tailwind @krizaka/tokens tailwindcssStyles
@import "tailwindcss";
@import "@krizaka/tailwind";
@import "@krizaka/ui/tailwind.css";Import
import { FilterBar, FilterMenu, readFilterParams, writeFilterParams } from "@krizaka/ui/filter-bar";Examples
Jobs
A search, a status menu (several values), a model menu (one value), the chips and the count.
6 jobs
A filter's menu
FilterMenu open: checkboxes with the count each value would give.
In the address
The filters read from and written to URLSearchParams, the page reset on change.
?role=creator%2Cadmin&page=3
Props
FilterBar
The bar of filters above a list: controls, active filters as chips, clear all, the count of results.
| Prop | Type | Default | Description |
|---|---|---|---|
labelrequired | string | — | The accessible name of the bar ("Filter jobs"), passed translated. |
active | readonly ActiveFilter[] | [] | The filters in force, each a removable chip. |
children | ReactNode | — | The controls: SearchField, FilterMenu, DateRangePicker, a Chip.Group… |
clearLabel | string | Clear filters | The "Clear all" button ("Clear filters"), passed translated. |
onClearAll | (() => void) | — | Clears every filter; the "Clear all" button shows when there is at least one. |
removeLabel | ((label: string) => string) | (text) => `Remove ${text}` | A chip's remove button: (label) => "Remove " + label, passed translated. |
results | string | — | The count of results ("42 jobs"), announced politely when it changes. |
FilterMenu
A filter's button and its menu of options — checkboxes (several values) or radios (one) — with a count of chosen ones.
| Prop | Type | Default | Description |
|---|---|---|---|
labelrequired | string | — | The name of the filter on its button ("Status"), passed translated. |
onValueChangerequired | ((value: string[]) => void) | ((value: string) => void) | — | Called with the values chosen. Called with the value chosen. |
optionsrequired | readonly FilterOption[] | — | The choices. |
valuerequired | string | readonly string[] | — | The values chosen.
The value chosen, "" for none. |
className | string | — | Classes merged on the button. |
defaultOpen | boolean | — | Opens the menu at first (a story, a test). |
multiple | boolean | — | Several values (checkboxes, default) or one (radios). One value: the options are radios. |
Accessibility
- The bar is a
groupnamed bylabel; each chip's remove button is named byremoveLabel(“Remove Status: Failed”). - The count of results is a polite live region: a change of filter is heard without moving the focus.
FilterMenuis a Radix menu of checkbox (or radio) items: their state is announced as they toggle.
Keyboard
| Keys | Action |
|---|---|
| Enter / Space / Arrow Down | Opens a filter's menu. |
| Arrow keys | Move between the options of an open menu; Space checks one, the menu stays open. |
| Esc | Closes the menu and returns to its button. |
Best practices
- Keep the filters in the address:
readFilterParamson load,writeFilterParams(which resets the page) on change. - Give each active chip the filter's name and value (“Status: Failed”), not the value alone.
- Count the results in
results(“42 jobs”): it is announced when it changes. - Use
FilterMenufor a list of values (checkboxes, or radios withmultiple={false}), aDateRangePickerfor a period.
Related components
Generated from the code of @krizaka/ui 2.4.0: its meta.ts, its examples and its types.Edit this documentation on GitHub