A bar of filters that users add, change and remove, each shown as a chip with its field and value.
- Add the registry
- Add filter-bar
Usage
fields lists what users can filter by. Each field's type sets the kind of value it takes:
selecttakes one option.multi-selecttakes any number of options.texttakes what someone types, such as a word to search for.date-rangetakes a range of days, from a preset or a calendar.customtakes any value, through an editor you render.
An option is a string, or an object with a value, a label, an icon and disabled.
The value maps each applied field's name to its value, as in { status: ["failed"], branch: "main" }.
A select field's value is an option's value, and a multi-select field's is an array of them. A
text field's value is the text, and a date-range field's is a FilterBarDateRange. A field without
a value has no key, so a missing key always means "no filter". FilterBar drops keys that no field
has the name of.
FilterBarAdd opens a menu of the fields. Choosing one shows its options, with a search input that
filters them. A select field applies its option and closes the menu. A multi-select field stays
open so users can choose several. Each chip that FilterBarItems renders opens the same options when
pressed, and its remove button removes the filter. To place one chip yourself, render a
FilterBarItem with the field's name in place of FilterBarItems. FilterBarClear returns the filters to
the fields' defaults. It renders only while the filters differ from them.
Persistent and read-only fields' chips come first, in the order of fields. The other chips follow
the value's keys, so a newly added filter goes after the others. Suggested chips come last.
A multi-select chip lists up to two options with Intl.ListFormat, as in "Failed or Cancelled".
With more, it shows the first option and the number of others, as in "Failed +2". Screen readers
announce the whole list as the chip's description. Pass a field a formatValue to show something else.
It receives the field's whole value, such as a multi-select field's array.
FilterBar isn't a form control. It has no name and doesn't take part in a form's submission or
reset. To send the filters to a server, read the value or use the URL helpers.
Searching
Typing in the menu searches the fields. It also searches the options of select, multi-select
and date-range fields, listed under each field's label. Choosing an option there applies it and
closes the menu. Choosing a checked option of a multi-select field unchecks it. Options from
loadOptions aren't searched there.
Accessibility
In the menu, Right Arrow at the end of the input opens the highlighted field's options. Left Arrow at the start of the input, or Backspace in an empty one, goes back to the fields. The arrow keys swap in a right-to-left language. The back button beside the input stays out of the tab order, since these keys do the same.
When a chip is removed, focus moves to the next chip that can be pressed, then to the previous one,
then to FilterBarAdd. Clearing the filters moves focus to FilterBarAdd. Screen readers announce each
filter that's added or removed, and the filters being cleared, through a live region in FilterBar.
When an option chosen from the search changes an applied filter, they announce its new value.
Composition
Examples
Filtering a table
Control value to filter data with it. Here, the rows of a Table are the
invoices whose status is any of the chosen ones and whose customer matches. FilterBarValue holds
unknown values, so the example checks each value's type before using it.
Text
A text field filters by what someone types. Enter or Apply applies the text. An empty value
removes the filter. placeholder sets the input's placeholder.
Date ranges
A date-range field lists its presets, then "Custom range…". That option opens a
Calendar to pick the first and last day. min and max limit the days it
offers.
A preset's range runs when someone chooses the preset. The value keeps the preset's value too,
so its chip shows the preset's label. A custom range's chip shows its days, written with
Intl.DateTimeFormat in the locale.
from and to are local midnights, and the range includes the whole of its last day. To test a
date against it, compare by day, or check that the date comes before the midnight after to.
Persistent fields
Set persistent on a field that belongs to the page rather than to something users opt into. Its
chip always shows, ahead of the others, and has no remove button. Without a value, the chip shows
"Any". A select or date-range field then offers Any to clear it. With a defaultValue as well,
the field can't be emptied: Any isn't offered, and the last option can't be unchecked.
A field's defaultValue is what FilterBarClear returns the field to. An uncontrolled FilterBar
without a defaultValue of its own also starts with the fields' defaults. When you control
value, start it with the defaults yourself.
Read-only
Set readOnly on a field whose value the page sets, such as the team the page belongs to. Its chip
shows the field's value, ahead of the others, but can't be changed or removed. The field is left
out of the menu and clearing. The URL helpers leave it out too, so merge its value back in when you
read the filters from the URL.
Suggestions
Give a field a suggestion for a value users often want. While the field has no value, a dashed
chip after the others suggests it. Pressing the chip applies the value. Screen readers announce
the chip as "Add Environment Production".
Loading options
Pass loadOptions in place of options to load them for what someone types, such as from a search
endpoint. It receives the query and a signal that aborts once the query changes. It runs once the
query stays the same for loadDelay milliseconds, through the
useAsyncSuggestions hook. While options load, the list shows a
spinner, and Enter doesn't pick an option left from the last query. A failed load shows the
loadError label.
emptyOptions lists the options to show before someone types, such as recent choices. Chips take
their labels from emptyOptions and from the options users choose. A value can come from
elsewhere, such as the URL, without either. Pass the field a formatValue then, to show its label.
Custom fields
A custom field renders its own editor in the menu with renderEditor. Use it for a value the
other types don't cover, such as a duration picked with a Slider.
renderEditor receives the field's value and an onValueChange that sets it. Passing
onValueChange undefined removes the filter. It also receives close, which closes the menu.
formatValue returns the text the chip and the menu show for the value. Type the field as
FilterBarCustomField<Value> to type the value its functions receive.
An editor that changes its value continuously, as a slider does while it's dragged, should set the
value once the change is done, as the slider below does with onValueCommitted. Otherwise each step
reaches onValueChange, and a URL synced to the value changes with every step.
The URL helpers skip a custom field unless it has both toParam and fromParam. toParam writes
the value as a search param, and fromParam reads it back.
Chips on their own
The chip parts work without FilterBar, for filters that something else applies, or a bar you build
around a Dropdown Menu. Wrap the label and value in a
FilterBarChipTrigger to make the chip a button, such as one that opens a
Popover to edit the filter. Leave out FilterBarChipRemove for a filter that
can't be removed.
FilterBarChipRemove takes its accessible name from its chip, so screen readers announce the first
removable chip below as "Remove Status Failed". Put a row of chips in a role="group" with an
aria-label. On their own, chips don't move focus when one is removed, so move it to a neighbor
yourself.
Syncing with the URL
Keeping the filters in the URL's search params lets them survive a reload and be shared as a link.
Control value with a library that manages search params, or with your router's own support for
them.
nuqs (opens in a new tab) keeps state in the search params in Next.js, React Router,
TanStack Router and other frameworks, once you set up its adapter. useQueryStates reads and writes
a parser per field. Setting a field to null removes its param.
TanStack Router (opens in a new tab) validates a route's
search params with validateSearch, and TanStack Start routes work the same way. The route's
useSearch reads them, and navigate writes them. Here a Zod (opens in a new tab) schema validates
the params when the route reads them and the value when the filters change.
Both examples cover select and multi-select fields, whose values are text. A date-range field
or a custom field needs a parser or schema of its own that writes its value as text and reads it
back.
For a router without its own support, filterValueFromSearchParams reads the filters from a
URLSearchParams, and filterValueToSearchParams writes them into one. Each field reads and writes
its own search param, its param or else its name. filterValueToSearchParams keeps the params
it's given that no field owns. A multi-select field repeats its param, as in
?status=Ready&status=Failed. A date range is written as its preset's value, or as its days, as
in 2026-09-07..2026-09-18.
A field that equals its defaultValue leaves its param out. When a field with a default has no
value, its param is kept but empty, so the removal survives a reload. Reading drops values that
aren't among a field's options, unless the field loads them with loadOptions. A value that's
dropped this way falls back to the field's default.
Labels
labels replaces the words the parts show and announce, including the group's accessible name.
FilterBarAdd and FilterBarClear take theirs as children. locale sets the language that chips list
options and write dates in.
Props
FilterBarAdd and FilterBarClear take the props of a Button. FilterBarAdd also
takes the portal and positioner props of PopoverContent, such as side
and align. FilterBarItem takes them too, and its menu lines up with its chip. FilterBarChipRemove
takes the props of a Button except variant and size.
Base UI's styling (opens in a new tab) and composition (opens in a new tab) guides say more about className, style and render.
FilterBar
FilterBarAdd
FilterBarItem
FilterBarClear
FilterBarChip
FilterBarChipTrigger
FilterBarChipLabel
FilterBarChipValue
FilterBarChipRemove
FilterBarSelectField
FilterBarMultiSelectField
FilterBarTextField
FilterBarDateRangeField
FilterBarCustomField
FilterBarCustomEditorProps
What a custom field's renderEditor receives.
FilterBarDatePreset
FilterBarDateRange
A date-range field's value.
FilterBarLabels
labels takes any of these, and keeps the English default for the rest.