Skip to content

Filter Bar

A bar of filters that users add, change and remove, each shown as a chip with its field and value.

Installation

  1. Add the registryOnce per project
  2. Add filter-bar

Usage

fields lists what users can filter by. Each field's type sets the kind of value it takes:

  • select takes one option.
  • multi-select takes any number of options.
  • text takes what someone types, such as a word to search for.
  • date-range takes a range of days, from a preset or a calendar.
  • custom takes 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.

TeamAcme

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.

DateLast 7 daysStatusFailedBranchmainAuthorTony Stark or Sam Rivera

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.

components/deployment-filters.tsx

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.