# Filter Bar

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

Source: [filter-bar.tsx](https://github.com/jakejarvis/jarvis-ui/blob/main/src/components/ui/filter-bar.tsx)

```tsx
import { CircleDashedIcon, GitBranchIcon, GlobeIcon, UserIcon } from "lucide-react";

import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
import {
  FilterBar,
  FilterBarAdd,
  FilterBarClear,
  FilterBarItems,
  type FilterBarField,
} from "@/components/ui/filter-bar";
import { Status } from "@/components/ui/status";
import { people } from "@/examples/data";

const fields: FilterBarField[] = [
  {
    name: "status",
    label: "Status",
    icon: <CircleDashedIcon />,
    type: "multi-select",
    options: [
      { value: "ready", label: "Ready", icon: <Status variant="success" /> },
      { value: "building", label: "Building", icon: <Status variant="warning" /> },
      { value: "failed", label: "Failed", icon: <Status variant="destructive" /> },
      { value: "cancelled", label: "Cancelled", icon: <Status /> },
    ],
  },
  {
    name: "environment",
    label: "Environment",
    icon: <GlobeIcon />,
    type: "select",
    options: ["Production", "Preview", "Development"],
  },
  {
    name: "branch",
    label: "Branch",
    icon: <GitBranchIcon />,
    type: "select",
    options: ["main", "canary", "feature/filter-bar-bar", "fix/login-redirect"],
  },
  {
    name: "author",
    label: "Author",
    icon: <UserIcon />,
    type: "multi-select",
    options: people.map((person) => ({
      value: person.value,
      label: person.name,
      icon: (
        <Avatar size="sm">
          <AvatarImage src={person.image} alt="" />
          <AvatarFallback>{person.initials}</AvatarFallback>
        </Avatar>
      ),
    })),
  },
];

export default function FilterBarBasic() {
  return (
    <FilterBar fields={fields} defaultValue={{ status: ["failed"], environment: "Production" }}>
      <FilterBarAdd />
      <FilterBarItems />
      <FilterBarClear />
    </FilterBar>
  );
}
```

## Installation

Add the registry, once per project:

```bash
npx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
```

Then add the component:

```bash
npx shadcn@latest add @jarvis/filter-bar
```

## Usage

```tsx
"use client";

import * as React from "react";

import {
  FilterBar,
  FilterBarAdd,
  FilterBarClear,
  FilterBarItems,
  type FilterBarField,
  type FilterBarValue,
} from "@/components/ui/filter-bar";

const fields: FilterBarField[] = [
  {
    name: "status",
    label: "Status",
    type: "multi-select",
    options: [
      { value: "ready", label: "Ready" },
      { value: "failed", label: "Failed" },
    ],
  },
  {
    name: "branch",
    label: "Branch",
    type: "select",
    options: ["main", "canary"],
  },
];

export function DeploymentFilters() {
  const [filters, setFilters] = React.useState<FilterBarValue>({});

  return (
    <FilterBar fields={fields} value={filters} onValueChange={setFilters}>
      <FilterBarAdd />
      <FilterBarItems />
      <FilterBarClear />
    </FilterBar>
  );
}
```

`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

- `FilterBar`
  - `FilterBarAdd`
  - `FilterBarItems`
  - `FilterBarItem`
  - `FilterBarClear`
- `FilterBarChip`
  - `FilterBarChipTrigger`
  - `FilterBarChipLabel`
  - `FilterBarChipValue`
  - `FilterBarChipRemove`

## Examples

### Filtering a table

Control `value` to filter data with it. Here, the rows of a [Table](https://ui.jarv.is/components/table.md) 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.

```tsx
"use client";

import * as React from "react";

import {
  FilterBar,
  FilterBarAdd,
  FilterBarClear,
  FilterBarItems,
  type FilterBarField,
  type FilterBarValue,
} from "@/components/ui/filter-bar";
import { Status } from "@/components/ui/status";
import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@/components/ui/table";

const statuses = {
  paid: { label: "Paid", variant: "success" },
  sent: { label: "Sent", variant: "info" },
  overdue: { label: "Overdue", variant: "destructive" },
  draft: { label: "Draft", variant: "default" },
} as const;

const invoices = [
  { id: "INV-1042", customer: "Acme Corp", status: "paid", amount: 6300 },
  { id: "INV-1043", customer: "Bluebird Studio", status: "sent", amount: 1800 },
  { id: "INV-1044", customer: "Acme Corp", status: "overdue", amount: 1275 },
  { id: "INV-1045", customer: "Driftwood Labs", status: "overdue", amount: 4500 },
  { id: "INV-1046", customer: "Bluebird Studio", status: "draft", amount: 600 },
  { id: "INV-1047", customer: "Driftwood Labs", status: "paid", amount: 2150 },
] as const;

const fields: FilterBarField[] = [
  {
    name: "status",
    label: "Status",
    type: "multi-select",
    options: Object.entries(statuses).map(([value, status]) => ({ value, label: status.label })),
  },
  {
    name: "customer",
    label: "Customer",
    type: "select",
    options: ["Acme Corp", "Bluebird Studio", "Driftwood Labs"],
  },
];

const currency = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" });

export default function FilterBarWithTable() {
  const [filters, setFilters] = React.useState<FilterBarValue>({ status: ["overdue", "sent"] });

  const status = Array.isArray(filters.status) ? filters.status : undefined;
  const customer = typeof filters.customer === "string" ? filters.customer : undefined;
  const rows = invoices.filter(
    (invoice) =>
      (!status || status.includes(invoice.status)) && (!customer || customer === invoice.customer),
  );

  return (
    <div className="flex w-full flex-col gap-3">
      <FilterBar fields={fields} value={filters} onValueChange={setFilters}>
        <FilterBarAdd />
        <FilterBarItems />
        <FilterBarClear />
      </FilterBar>
      <Table>
        <TableHeader>
          <TableRow>
            <TableHead>Invoice</TableHead>
            <TableHead>Customer</TableHead>
            <TableHead>Status</TableHead>
            <TableHead className="text-right">Amount</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {rows.map((invoice) => (
            <TableRow key={invoice.id}>
              <TableCell className="font-mono">{invoice.id}</TableCell>
              <TableCell className="font-medium">{invoice.customer}</TableCell>
              <TableCell>
                <Status variant={statuses[invoice.status].variant}>
                  {statuses[invoice.status].label}
                </Status>
              </TableCell>
              <TableCell className="text-right">{currency.format(invoice.amount)}</TableCell>
            </TableRow>
          ))}
          {rows.length === 0 && (
            <TableRow>
              <TableCell colSpan={4} className="h-20 text-center text-muted-foreground">
                No invoices match these filters.
              </TableCell>
            </TableRow>
          )}
        </TableBody>
      </Table>
    </div>
  );
}
```

### 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.

```tsx
import { CircleDashedIcon, TextIcon } from "lucide-react";

import {
  FilterBar,
  FilterBarAdd,
  FilterBarClear,
  FilterBarItems,
  type FilterBarField,
} from "@/components/ui/filter-bar";

const fields: FilterBarField[] = [
  {
    name: "message",
    label: "Message",
    icon: <TextIcon />,
    type: "text",
    placeholder: "Search log messages…",
  },
  {
    name: "level",
    label: "Level",
    icon: <CircleDashedIcon />,
    type: "multi-select",
    options: ["Info", "Warning", "Error"],
  },
];

export default function FilterBarText() {
  return (
    <FilterBar fields={fields} defaultValue={{ message: "timeout", level: ["Error"] }}>
      <FilterBarAdd />
      <FilterBarItems />
      <FilterBarClear />
    </FilterBar>
  );
}
```

### Date ranges

A `date-range` field lists its `presets`, then "Custom range…". That option opens a
[Calendar](https://ui.jarv.is/components/calendar.md) 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`.

```tsx
"use client";

import { CalendarIcon, CircleDashedIcon } from "lucide-react";

import {
  FilterBar,
  FilterBarAdd,
  FilterBarClear,
  FilterBarItems,
  type FilterBarField,
} from "@/components/ui/filter-bar";

function daysAgo(days: number) {
  const date = new Date();
  date.setHours(0, 0, 0, 0);
  date.setDate(date.getDate() - days);
  return date;
}

const fields: FilterBarField[] = [
  {
    name: "created",
    label: "Created",
    icon: <CalendarIcon />,
    type: "date-range",
    presets: [
      { value: "today", label: "Today", range: () => ({ from: daysAgo(0), to: daysAgo(0) }) },
      { value: "7d", label: "Last 7 days", range: () => ({ from: daysAgo(6), to: daysAgo(0) }) },
      { value: "30d", label: "Last 30 days", range: () => ({ from: daysAgo(29), to: daysAgo(0) }) },
    ],
  },
  {
    name: "status",
    label: "Status",
    icon: <CircleDashedIcon />,
    type: "multi-select",
    options: ["Ready", "Building", "Failed"],
  },
];

export default function FilterBarDateRanges() {
  return (
    <FilterBar
      fields={fields}
      defaultValue={{ created: { from: new Date(2026, 8, 7), to: new Date(2026, 8, 18) } }}
    >
      <FilterBarAdd />
      <FilterBarItems />
      <FilterBarClear />
    </FilterBar>
  );
}
```

### 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.

```tsx
import { CircleDashedIcon, GitBranchIcon, GlobeIcon } from "lucide-react";

import {
  FilterBar,
  FilterBarAdd,
  FilterBarClear,
  FilterBarItems,
  type FilterBarField,
} from "@/components/ui/filter-bar";

const fields: FilterBarField[] = [
  {
    name: "environment",
    label: "Environment",
    icon: <GlobeIcon />,
    type: "select",
    options: ["Production", "Preview", "Development"],
    persistent: true,
    defaultValue: "Production",
  },
  {
    name: "status",
    label: "Status",
    icon: <CircleDashedIcon />,
    type: "multi-select",
    options: ["Ready", "Building", "Failed"],
    persistent: true,
  },
  {
    name: "branch",
    label: "Branch",
    icon: <GitBranchIcon />,
    type: "select",
    options: ["main", "canary", "feature/filter-bar-bar"],
  },
];

export default function FilterBarPersistent() {
  return (
    <FilterBar fields={fields}>
      <FilterBarAdd />
      <FilterBarItems />
      <FilterBarClear />
    </FilterBar>
  );
}
```

### 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.

```tsx
import { CircleDashedIcon, UsersIcon } from "lucide-react";

import {
  FilterBar,
  FilterBarAdd,
  FilterBarClear,
  FilterBarItems,
  type FilterBarField,
} from "@/components/ui/filter-bar";

const fields: FilterBarField[] = [
  {
    name: "team",
    label: "Team",
    icon: <UsersIcon />,
    type: "select",
    options: [{ value: "acme", label: "Acme" }],
    readOnly: true,
  },
  {
    name: "status",
    label: "Status",
    icon: <CircleDashedIcon />,
    type: "multi-select",
    options: ["Ready", "Building", "Failed"],
  },
];

export default function FilterBarReadOnly() {
  return (
    <FilterBar fields={fields} defaultValue={{ team: "acme", status: ["Failed"] }}>
      <FilterBarAdd />
      <FilterBarItems />
      <FilterBarClear />
    </FilterBar>
  );
}
```

### 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".

```tsx
import { CircleDashedIcon, GitBranchIcon, GlobeIcon } from "lucide-react";

import {
  FilterBar,
  FilterBarAdd,
  FilterBarClear,
  FilterBarItems,
  type FilterBarField,
} from "@/components/ui/filter-bar";

const fields: FilterBarField[] = [
  {
    name: "environment",
    label: "Environment",
    icon: <GlobeIcon />,
    type: "select",
    options: ["Production", "Preview", "Development"],
    suggestion: "Production",
  },
  {
    name: "status",
    label: "Status",
    icon: <CircleDashedIcon />,
    type: "multi-select",
    options: ["Ready", "Building", "Failed"],
    suggestion: ["Failed"],
  },
  {
    name: "branch",
    label: "Branch",
    icon: <GitBranchIcon />,
    type: "select",
    options: ["main", "canary", "feature/filter-bar-bar"],
  },
];

export default function FilterBarSuggestions() {
  return (
    <FilterBar fields={fields}>
      <FilterBarAdd />
      <FilterBarItems />
      <FilterBarClear />
    </FilterBar>
  );
}
```

### 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](https://ui.jarv.is/hooks/use-async-suggestions.md) 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.

```tsx
"use client";

import { UserIcon } from "lucide-react";

import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
import {
  FilterBar,
  FilterBarAdd,
  FilterBarClear,
  FilterBarItems,
  type FilterBarField,
  type FilterBarOption,
} from "@/components/ui/filter-bar";
import { people, searchPeople, type Person } from "@/examples/data";

function toOption(person: Person): FilterBarOption {
  return {
    value: person.value,
    label: person.name,
    icon: (
      <Avatar size="sm">
        <AvatarImage src={person.image} alt="" />
        <AvatarFallback>{person.initials}</AvatarFallback>
      </Avatar>
    ),
  };
}

const fields: FilterBarField[] = [
  {
    name: "author",
    label: "Author",
    icon: <UserIcon />,
    type: "multi-select",
    loadOptions: async (query, { signal }) => (await searchPeople(query, { signal })).map(toOption),
    emptyOptions: people.slice(0, 3).map(toOption),
  },
];

export default function FilterBarAsyncOptions() {
  return (
    <FilterBar fields={fields} defaultValue={{ author: ["tony"] }}>
      <FilterBarAdd />
      <FilterBarItems />
      <FilterBarClear />
    </FilterBar>
  );
}
```

### 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](https://ui.jarv.is/components/slider.md).
`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.

```tsx
"use client";

import { CircleDashedIcon, TimerIcon } from "lucide-react";
import * as React from "react";

import {
  FilterBar,
  FilterBarAdd,
  FilterBarClear,
  FilterBarItems,
  type FilterBarCustomEditorProps,
  type FilterBarCustomField,
  type FilterBarField,
} from "@/components/ui/filter-bar";
import { Slider, SliderLabel, SliderValue } from "@/components/ui/slider";

const minutes = new Intl.NumberFormat("en-US", {
  style: "unit",
  unit: "minute",
  unitDisplay: "short",
});

function DurationEditor({ value, onValueChange }: FilterBarCustomEditorProps<number>) {
  const [duration, setDuration] = React.useState(value ?? 1);

  return (
    <Slider
      value={duration}
      min={1}
      max={30}
      format={{ style: "unit", unit: "minute", unitDisplay: "short" }}
      onValueChange={setDuration}
      onValueCommitted={(next, eventDetails) => onValueChange(next, eventDetails.event)}
    >
      <SliderLabel>Longer than</SliderLabel>
      <SliderValue />
    </Slider>
  );
}

const duration: FilterBarCustomField<number> = {
  name: "duration",
  label: "Duration",
  icon: <TimerIcon />,
  type: "custom",
  renderEditor: (props) => <DurationEditor {...props} />,
  formatValue: (value) => `Over ${minutes.format(value)}`,
  toParam: String,
  fromParam: (param) => {
    const value = Number(param);
    return Number.isInteger(value) && value >= 1 && value <= 30 ? value : undefined;
  },
};

const fields: FilterBarField[] = [
  duration,
  {
    name: "status",
    label: "Status",
    icon: <CircleDashedIcon />,
    type: "multi-select",
    options: ["Ready", "Building", "Failed"],
  },
];

export default function FilterBarDuration() {
  return (
    <FilterBar fields={fields} defaultValue={{ duration: 5 }}>
      <FilterBarAdd />
      <FilterBarItems />
      <FilterBarClear />
    </FilterBar>
  );
}
```

### 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](https://ui.jarv.is/components/dropdown-menu.md). Wrap the label and value in a
`FilterBarChipTrigger` to make the chip a button, such as one that opens a
[Popover](https://ui.jarv.is/components/popover.md) 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.

```tsx
"use client";

import * as React from "react";

import { Button } from "@/components/ui/button";
import {
  FilterBarChip,
  FilterBarChipLabel,
  FilterBarChipRemove,
  FilterBarChipValue,
} from "@/components/ui/filter-bar";

const initialFilters = [
  { field: "Status", value: "Failed" },
  { field: "Branch", value: "main" },
  { field: "Author", value: "Tony Stark or Sam Rivera" },
];

export default function FilterBarChips() {
  const [filters, setFilters] = React.useState(initialFilters);

  return (
    <div role="group" aria-label="Filters" className="flex flex-wrap items-center gap-2">
      <FilterBarChip>
        <FilterBarChipLabel>Date</FilterBarChipLabel>
        <FilterBarChipValue>Last 7 days</FilterBarChipValue>
      </FilterBarChip>
      {filters.map((filter) => (
        <FilterBarChip key={filter.field}>
          <FilterBarChipLabel>{filter.field}</FilterBarChipLabel>
          <FilterBarChipValue>{filter.value}</FilterBarChipValue>
          <FilterBarChipRemove
            onClick={() => setFilters((list) => list.filter((item) => item !== filter))}
          />
        </FilterBarChip>
      ))}
      {filters.length === 0 && (
        <Button variant="ghost" onClick={() => setFilters(initialFilters)}>
          Reset filters
        </Button>
      )}
    </div>
  );
}
```

### 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**

```bash
npm install nuqs
```

[nuqs](https://nuqs.dev/docs/basic-usage) 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.

```tsx title="components/deployment-filters.tsx"
"use client";

import { parseAsArrayOf, parseAsString, useQueryStates } from "nuqs";

import {
  FilterBar,
  FilterBarAdd,
  FilterBarClear,
  FilterBarItems,
  type FilterBarField,
  type FilterBarValue,
} from "@/components/ui/filter-bar";

const fields: FilterBarField[] = [
  {
    name: "status",
    label: "Status",
    type: "multi-select",
    options: ["Ready", "Building", "Failed"],
  },
  {
    name: "branch",
    label: "Branch",
    type: "select",
    options: ["main", "canary"],
  },
];

export function DeploymentFilters() {
  const [search, setSearch] = useQueryStates({
    status: parseAsArrayOf(parseAsString),
    branch: parseAsString,
  });

  const value: FilterBarValue = {};
  if (search.status) value.status = search.status;
  if (search.branch) value.branch = search.branch;

  return (
    <FilterBar
      fields={fields}
      value={value}
      onValueChange={(next) =>
        setSearch({
          status: Array.isArray(next.status) ? next.status : null,
          branch: typeof next.branch === "string" ? next.branch : null,
        })
      }
    >
      <FilterBarAdd />
      <FilterBarItems />
      <FilterBarClear />
    </FilterBar>
  );
}
```

**TanStack Router**

```bash
npm install zod
```

[TanStack Router](https://tanstack.com/router/latest/docs/guide/search-params) 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](https://zod.dev) schema validates
the params when the route reads them and the value when the filters change.

```tsx title="src/routes/deployments.tsx"
import { createFileRoute } from "@tanstack/react-router";
import { z } from "zod";

import {
  FilterBar,
  FilterBarAdd,
  FilterBarClear,
  FilterBarItems,
  type FilterBarField,
} from "@/components/ui/filter-bar";

const fields: FilterBarField[] = [
  {
    name: "status",
    label: "Status",
    type: "multi-select",
    options: ["Ready", "Building", "Failed"],
  },
  {
    name: "branch",
    label: "Branch",
    type: "select",
    options: ["main", "canary"],
  },
];

const searchSchema = z.object({
  status: z.array(z.string()).optional().catch(undefined),
  branch: z.string().optional().catch(undefined),
});

export const Route = createFileRoute("/deployments")({
  validateSearch: searchSchema,
  component: Deployments,
});

function Deployments() {
  const search = Route.useSearch();
  const navigate = Route.useNavigate();

  return (
    <FilterBar
      fields={fields}
      value={search}
      onValueChange={(value) => navigate({ search: searchSchema.parse(value), replace: true })}
    >
      <FilterBarAdd />
      <FilterBarItems />
      <FilterBarClear />
    </FilterBar>
  );
}
```

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.

```tsx
"use client";

import {
  FilterBar,
  FilterBarAdd,
  FilterBarClear,
  FilterBarItems,
  type FilterBarField,
} from "@/components/ui/filter-bar";

const fields: FilterBarField[] = [
  {
    name: "status",
    label: "Status",
    type: "multi-select",
    options: [
      { value: "ready", label: "Bereit" },
      { value: "failed", label: "Fehlgeschlagen" },
      { value: "cancelled", label: "Abgebrochen" },
    ],
  },
  {
    name: "environment",
    label: "Umgebung",
    type: "select",
    options: [
      { value: "production", label: "Produktion" },
      { value: "preview", label: "Vorschau" },
    ],
  },
];

export default function FilterBarCustomLabels() {
  return (
    <FilterBar
      fields={fields}
      defaultValue={{ status: ["failed", "cancelled"] }}
      locale="de-DE"
      labels={{
        group: "Filter",
        fieldsPlaceholder: "Filtern nach…",
        optionsPlaceholder: "Suchen…",
        empty: "Keine Ergebnisse.",
        back: "Zurück",
        remove: (field, value) => `${field} ${value} entfernen`,
        added: (field) => `Filter ${field} hinzugefügt`,
        removed: (field) => `Filter ${field} entfernt`,
        cleared: "Filter zurückgesetzt",
      }}
    >
      <FilterBarAdd>Filter hinzufügen</FilterBarAdd>
      <FilterBarItems />
      <FilterBarClear>Zurücksetzen</FilterBarClear>
    </FilterBar>
  );
}
```

## Props

`FilterBarAdd` and `FilterBarClear` take the props of a [Button](https://ui.jarv.is/components/button.md). `FilterBarAdd` also
takes the portal and positioner props of [`PopoverContent`](https://ui.jarv.is/components/popover.md), 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`.

| Part | Extends |
| --- | --- |
| `FilterBar` | `<div>` |
| `FilterBarAdd` | [`Button`](https://ui.jarv.is/components/button.md) |
| `FilterBarItems` | — |
| `FilterBarItem` | `<span>` |
| `FilterBarClear` | [`Button`](https://ui.jarv.is/components/button.md) |
| `FilterBarChip` | `<span>` |
| `FilterBarChipTrigger` | `<button>` |
| `FilterBarChipLabel` | `<span>` |
| `FilterBarChipValue` | `<span>` |
| `FilterBarChipRemove` | [`Button`](https://ui.jarv.is/components/button.md) |

Base UI's [styling](https://base-ui.com/react/handbook/styling) and [composition](https://base-ui.com/react/handbook/composition) guides say more about `className`, `style` and `render`.

### FilterBar

| Prop             | Type                                                                           | Default                           | Description                                                                                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fields`         | `readonly FilterBarField[]`                                                    | —                                 | The fields users can filter by, in the order the menu lists them.                                                                                                                         |
| `value?`         | `FilterBarValue`                                                               | —                                 | The applied filters, keyed by field name, in the order their chips appear. Use when controlled.                                                                                           |
| `defaultValue?`  | `FilterBarValue`                                                               | `` The fields' `defaultValue`s `` | The filters applied when the component first renders. Use when uncontrolled.                                                                                                              |
| `onValueChange?` | `((value: FilterBarValue, eventDetails: FilterBarChangeEventDetails) => void)` | —                                 | Called when a filter is added, changed or removed, with the new value.                                                                                                                    |
| `labels?`        | `FilterBarLabels`                                                              | —                                 | The words the parts show or announce, to replace for another language.                                                                                                                    |
| `locale?`        | `string`                                                                       | `"en-US"`                         | The BCP 47 language tag the chips' lists, numbers and dates are written in.                                                                                                               |
| `disabled?`      | `boolean`                                                                      | `false`                           | Whether users can't add, change or remove filters.                                                                                                                                        |
| `className?`     | `string`                                                                       | —                                 | CSS class applied to the element.                                                                                                                                                         |
| `style?`         | `React.CSSProperties`                                                          | —                                 | Style applied to the element.                                                                                                                                                             |
| `render?`        | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement`                       | —                                 | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### FilterBarAdd

| Prop                     | Type                                                                                                                 | Default                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `focusableWhenDisabled?` | `boolean`                                                                                                            | `false`                        | Whether the button should be focusable when disabled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `nativeButton?`          | `boolean`                                                                                                            | `true`                         | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `variant?`               | `"destructive" \| "ghost" \| "link" \| "outline" \| "primary" \| "secondary"`                                        | `"secondary"`                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `size?`                  | `"default" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xs" \| "lg" \| "sm" \| "xs"`                                 | `"default"`                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `anchor?`                | `Element \| React.RefObject<Element \| null> \| VirtualElement \| (() => Element \| VirtualElement \| null) \| null` | —                              | An element to position the popup against. By default, the popup will be positioned against the trigger.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `positionMethod?`        | `"absolute" \| "fixed"`                                                                                              | `'absolute'`                   | Determines which CSS `position` property to use.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `side?`                  | `"bottom" \| "inline-end" \| "inline-start" \| "left" \| "right" \| "top"`                                           | `'bottom'`                     | Which side of the anchor element to align the popup against. May automatically change to avoid collisions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `sideOffset?`            | `number \| OffsetFunction`                                                                                           | `4`                            | Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `align?`                 | `"center" \| "end" \| "start"`                                                                                       | `"start"`                      | How to align the popup relative to the specified side.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `alignOffset?`           | `number \| OffsetFunction`                                                                                           | `0`                            | Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `collisionBoundary?`     | `Boundary`                                                                                                           | `'clipping-ancestors'`         | An element or a rectangle that delimits the area that the popup is confined to.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `collisionPadding?`      | `Padding`                                                                                                            | `5`                            | Additional space to maintain from the edge of the collision boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `sticky?`                | `boolean`                                                                                                            | `false`                        | Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `arrowPadding?`          | `number`                                                                                                             | `5`                            | Minimum distance to maintain between the arrow and the edges of the popup. Use it to prevent the arrow element from hanging out of the rounded corners of a popup.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `disableAnchorTracking?` | `boolean`                                                                                                            | `false`                        | Whether to disable the popup from tracking any layout shift of its positioning anchor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `collisionAvoidance?`    | `CollisionAvoidance`                                                                                                 | `{ fallbackAxisSide: "none" }` | Determines how to handle collisions when positioning the popup. `side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`): - `'flip'`: keep the requested side when it fits; otherwise try the opposite side (`top` and `bottom`, or `left` and `right`). - `'shift'`: never change side; keep the requested side and move the popup within the clipping boundary so it stays visible. - `'none'`: do not correct side-axis overflow. `align` controls overflow on the alignment axis (`start`/`center`/`end`): - `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows. - `'shift'`: keep side and requested alignment, then nudge the popup along the alignment axis to fit. - `'none'`: do not correct alignment-axis overflow. `fallbackAxisSide` controls fallback behavior on the perpendicular axis when the preferred axis cannot fit: - `'start'`: allow perpendicular fallback and try the logical start side first (`top` before `bottom`, or `left` before `right` in LTR). - `'end'`: allow perpendicular fallback and try the logical end side first (`bottom` before `top`, or `right` before `left` in LTR). - `'none'`: do not fallback to the perpendicular axis. When `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`. If `align` is omitted, it defaults to `'flip'`. |
| `keepMounted?`           | `boolean`                                                                                                            | `false`                        | Whether to keep the portal mounted in the DOM while the popup is hidden.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `container?`             | `HTMLElement \| React.RefObject<HTMLElement \| ShadowRoot \| null> \| ShadowRoot \| null`                            | —                              | A parent element to render the portal element into.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `className?`             | `string \| ((state: ButtonState) => string \| undefined)`                                                            | —                              | CSS class applied to the element, or a function that returns a class based on the component's state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `style?`                 | `React.CSSProperties \| ((state: ButtonState) => React.CSSProperties \| undefined)`                                  | —                              | Style applied to the element, or a function that returns a style object based on the component's state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `render?`                | `ComponentRenderFn<HTMLProps, ButtonState> \| React.ReactElement`                                                    | —                              | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

### FilterBarItem

| Prop                     | Type                                                                                                                 | Default                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `anchor?`                | `Element \| React.RefObject<Element \| null> \| VirtualElement \| (() => Element \| VirtualElement \| null) \| null` | —                              | An element to position the popup against. By default, the popup will be positioned against the trigger.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `positionMethod?`        | `"absolute" \| "fixed"`                                                                                              | `'absolute'`                   | Determines which CSS `position` property to use.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `side?`                  | `"bottom" \| "inline-end" \| "inline-start" \| "left" \| "right" \| "top"`                                           | `'bottom'`                     | Which side of the anchor element to align the popup against. May automatically change to avoid collisions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `sideOffset?`            | `number \| OffsetFunction`                                                                                           | `4`                            | Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `align?`                 | `"center" \| "end" \| "start"`                                                                                       | `"start"`                      | How to align the popup relative to the specified side.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `alignOffset?`           | `number \| OffsetFunction`                                                                                           | `0`                            | Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `collisionBoundary?`     | `Boundary`                                                                                                           | `'clipping-ancestors'`         | An element or a rectangle that delimits the area that the popup is confined to.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `collisionPadding?`      | `Padding`                                                                                                            | `5`                            | Additional space to maintain from the edge of the collision boundary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `sticky?`                | `boolean`                                                                                                            | `false`                        | Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `arrowPadding?`          | `number`                                                                                                             | `5`                            | Minimum distance to maintain between the arrow and the edges of the popup. Use it to prevent the arrow element from hanging out of the rounded corners of a popup.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `disableAnchorTracking?` | `boolean`                                                                                                            | `false`                        | Whether to disable the popup from tracking any layout shift of its positioning anchor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `collisionAvoidance?`    | `CollisionAvoidance`                                                                                                 | `{ fallbackAxisSide: "none" }` | Determines how to handle collisions when positioning the popup. `side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`): - `'flip'`: keep the requested side when it fits; otherwise try the opposite side (`top` and `bottom`, or `left` and `right`). - `'shift'`: never change side; keep the requested side and move the popup within the clipping boundary so it stays visible. - `'none'`: do not correct side-axis overflow. `align` controls overflow on the alignment axis (`start`/`center`/`end`): - `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows. - `'shift'`: keep side and requested alignment, then nudge the popup along the alignment axis to fit. - `'none'`: do not correct alignment-axis overflow. `fallbackAxisSide` controls fallback behavior on the perpendicular axis when the preferred axis cannot fit: - `'start'`: allow perpendicular fallback and try the logical start side first (`top` before `bottom`, or `left` before `right` in LTR). - `'end'`: allow perpendicular fallback and try the logical end side first (`bottom` before `top`, or `right` before `left` in LTR). - `'none'`: do not fallback to the perpendicular axis. When `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`. If `align` is omitted, it defaults to `'flip'`. |
| `keepMounted?`           | `boolean`                                                                                                            | `false`                        | Whether to keep the portal mounted in the DOM while the popup is hidden.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `container?`             | `HTMLElement \| React.RefObject<HTMLElement \| ShadowRoot \| null> \| ShadowRoot \| null`                            | —                              | A parent element to render the portal element into.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `name`                   | `string`                                                                                                             | —                              | The name of the field the chip shows. Without a value, it renders the field's suggestion, or nothing, unless the field is persistent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `className?`             | `string`                                                                                                             | —                              | CSS class applied to the element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `style?`                 | `React.CSSProperties`                                                                                                | —                              | Style applied to the element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `render?`                | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement`                                                             | —                              | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

### FilterBarClear

| Prop                     | Type                                                                                 | Default     | Description                                                                                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `focusableWhenDisabled?` | `boolean`                                                                            | `false`     | Whether the button should be focusable when disabled.                                                                                                                                     |
| `nativeButton?`          | `boolean`                                                                            | `true`      | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).         |
| `variant?`               | `"destructive" \| "ghost" \| "link" \| "outline" \| "primary" \| "secondary"`        | `"ghost"`   |                                                                                                                                                                                           |
| `size?`                  | `"default" \| "icon" \| "icon-lg" \| "icon-sm" \| "icon-xs" \| "lg" \| "sm" \| "xs"` | `"default"` |                                                                                                                                                                                           |
| `className?`             | `string \| ((state: ButtonState) => string \| undefined)`                            | —           | CSS class applied to the element, or a function that returns a class based on the component's state.                                                                                      |
| `style?`                 | `React.CSSProperties \| ((state: ButtonState) => React.CSSProperties \| undefined)`  | —           | Style applied to the element, or a function that returns a style object based on the component's state.                                                                                   |
| `render?`                | `ComponentRenderFn<HTMLProps, ButtonState> \| React.ReactElement`                    | —           | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### FilterBarChip

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### FilterBarChipTrigger

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### FilterBarChipLabel

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### FilterBarChipValue

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### FilterBarChipRemove

| Prop                     | Type                                                                                | Default | Description                                                                                                                                                                               |
| ------------------------ | ----------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nativeButton?`          | `boolean`                                                                           | `true`  | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).         |
| `focusableWhenDisabled?` | `boolean`                                                                           | `false` | Whether the button should be focusable when disabled.                                                                                                                                     |
| `className?`             | `string \| ((state: ButtonState) => string \| undefined)`                           | —       | CSS class applied to the element, or a function that returns a class based on the component's state.                                                                                      |
| `style?`                 | `React.CSSProperties \| ((state: ButtonState) => React.CSSProperties \| undefined)` | —       | Style applied to the element, or a function that returns a style object based on the component's state.                                                                                   |
| `render?`                | `ComponentRenderFn<HTMLProps, ButtonState> \| React.ReactElement`                   | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### FilterBarSelectField

| Property        | Type                                   | Default | Description                                                                                                                                                                                           |
| --------------- | -------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`          | `string`                               | —       | The field's key in the value.                                                                                                                                                                         |
| `label`         | `string`                               | —       | The field's name, shown in the menu and on its chip.                                                                                                                                                  |
| `icon?`         | `React.ReactNode`                      | —       | Shown before the label in the menu.                                                                                                                                                                   |
| `param?`        | `string`                               | —       | The search param the URL helpers read and write the field's value as. Defaults to `name`.                                                                                                             |
| `persistent?`   | `boolean`                              | —       | Keeps the field's chip in the bar, ahead of the others, even without a value, when it shows the `any` label. The chip has no remove button.                                                           |
| `defaultValue?` | `string`                               | —       | The value the field returns to when the filters are cleared. An uncontrolled `FilterBar` without a `defaultValue` of its own also starts with it. A persistent field with a default can't be emptied. |
| `readOnly?`     | `boolean`                              | —       | Shows the field's value as a chip that can't be changed or removed, such as context the page sets. The field is left out of the menu, the URL and clearing.                                           |
| `suggestion?`   | `string`                               | —       | A value to suggest while the field has none. It shows as a dashed chip, which applies the value when pressed.                                                                                         |
| `formatValue?`  | `((value: string) => React.ReactNode)` | —       | Returns what the chip shows for the field's value. When it returns a string, screen readers hear that text too, in the chip's labels and announcements.                                               |
| `type`          | `"select"`                             | —       | Which kind of value the field takes, and how users choose it.                                                                                                                                         |
| `options?`      | `readonly FilterBarOption[]`           | —       | The options users choose from.                                                                                                                                                                        |
| `loadOptions?`  | `FilterBarLoadOptions`                 | —       | Loads the options for what someone types, such as from a search endpoint, in place of `options`. It receives a signal that aborts once the query changes.                                             |
| `loadDelay?`    | `number`                               | `300`   | How long the query has to stay the same before `loadOptions` runs, in milliseconds.                                                                                                                   |
| `emptyOptions?` | `readonly FilterBarOption[]`           | —       | With `loadOptions`, the options to show before someone types, such as recent choices. They also give the chips the labels of these values.                                                            |

### FilterBarMultiSelectField

| Property        | Type                                     | Default | Description                                                                                                                                                                                           |
| --------------- | ---------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`          | `string`                                 | —       | The field's key in the value.                                                                                                                                                                         |
| `label`         | `string`                                 | —       | The field's name, shown in the menu and on its chip.                                                                                                                                                  |
| `icon?`         | `React.ReactNode`                        | —       | Shown before the label in the menu.                                                                                                                                                                   |
| `param?`        | `string`                                 | —       | The search param the URL helpers read and write the field's value as. Defaults to `name`.                                                                                                             |
| `persistent?`   | `boolean`                                | —       | Keeps the field's chip in the bar, ahead of the others, even without a value, when it shows the `any` label. The chip has no remove button.                                                           |
| `defaultValue?` | `string[]`                               | —       | The value the field returns to when the filters are cleared. An uncontrolled `FilterBar` without a `defaultValue` of its own also starts with it. A persistent field with a default can't be emptied. |
| `readOnly?`     | `boolean`                                | —       | Shows the field's value as a chip that can't be changed or removed, such as context the page sets. The field is left out of the menu, the URL and clearing.                                           |
| `suggestion?`   | `string[]`                               | —       | A value to suggest while the field has none. It shows as a dashed chip, which applies the value when pressed.                                                                                         |
| `formatValue?`  | `((value: string[]) => React.ReactNode)` | —       | Returns what the chip shows for the field's value. When it returns a string, screen readers hear that text too, in the chip's labels and announcements.                                               |
| `type`          | `"multi-select"`                         | —       | Which kind of value the field takes, and how users choose it.                                                                                                                                         |
| `options?`      | `readonly FilterBarOption[]`             | —       | The options users choose from.                                                                                                                                                                        |
| `loadOptions?`  | `FilterBarLoadOptions`                   | —       | Loads the options for what someone types, such as from a search endpoint, in place of `options`. It receives a signal that aborts once the query changes.                                             |
| `loadDelay?`    | `number`                                 | `300`   | How long the query has to stay the same before `loadOptions` runs, in milliseconds.                                                                                                                   |
| `emptyOptions?` | `readonly FilterBarOption[]`             | —       | With `loadOptions`, the options to show before someone types, such as recent choices. They also give the chips the labels of these values.                                                            |

### FilterBarTextField

| Property        | Type                                   | Default | Description                                                                                                                                                                                           |
| --------------- | -------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`          | `string`                               | —       | The field's key in the value.                                                                                                                                                                         |
| `label`         | `string`                               | —       | The field's name, shown in the menu and on its chip.                                                                                                                                                  |
| `icon?`         | `React.ReactNode`                      | —       | Shown before the label in the menu.                                                                                                                                                                   |
| `param?`        | `string`                               | —       | The search param the URL helpers read and write the field's value as. Defaults to `name`.                                                                                                             |
| `persistent?`   | `boolean`                              | —       | Keeps the field's chip in the bar, ahead of the others, even without a value, when it shows the `any` label. The chip has no remove button.                                                           |
| `defaultValue?` | `string`                               | —       | The value the field returns to when the filters are cleared. An uncontrolled `FilterBar` without a `defaultValue` of its own also starts with it. A persistent field with a default can't be emptied. |
| `readOnly?`     | `boolean`                              | —       | Shows the field's value as a chip that can't be changed or removed, such as context the page sets. The field is left out of the menu, the URL and clearing.                                           |
| `suggestion?`   | `string`                               | —       | A value to suggest while the field has none. It shows as a dashed chip, which applies the value when pressed.                                                                                         |
| `formatValue?`  | `((value: string) => React.ReactNode)` | —       | Returns what the chip shows for the field's value. When it returns a string, screen readers hear that text too, in the chip's labels and announcements.                                               |
| `type`          | `"text"`                               | —       | Which kind of value the field takes, and how users choose it.                                                                                                                                         |
| `placeholder?`  | `string`                               | —       | The input's placeholder. Defaults to the `textPlaceholder` label.                                                                                                                                     |

### FilterBarDateRangeField

| Property        | Type                                               | Default | Description                                                                                                                                                                                           |
| --------------- | -------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`          | `string`                                           | —       | The field's key in the value.                                                                                                                                                                         |
| `label`         | `string`                                           | —       | The field's name, shown in the menu and on its chip.                                                                                                                                                  |
| `icon?`         | `React.ReactNode`                                  | —       | Shown before the label in the menu.                                                                                                                                                                   |
| `param?`        | `string`                                           | —       | The search param the URL helpers read and write the field's value as. Defaults to `name`.                                                                                                             |
| `persistent?`   | `boolean`                                          | —       | Keeps the field's chip in the bar, ahead of the others, even without a value, when it shows the `any` label. The chip has no remove button.                                                           |
| `defaultValue?` | `FilterBarDateRange`                               | —       | The value the field returns to when the filters are cleared. An uncontrolled `FilterBar` without a `defaultValue` of its own also starts with it. A persistent field with a default can't be emptied. |
| `readOnly?`     | `boolean`                                          | —       | Shows the field's value as a chip that can't be changed or removed, such as context the page sets. The field is left out of the menu, the URL and clearing.                                           |
| `suggestion?`   | `FilterBarDateRange`                               | —       | A value to suggest while the field has none. It shows as a dashed chip, which applies the value when pressed.                                                                                         |
| `formatValue?`  | `((value: FilterBarDateRange) => React.ReactNode)` | —       | Returns what the chip shows for the field's value. When it returns a string, screen readers hear that text too, in the chip's labels and announcements.                                               |
| `type`          | `"date-range"`                                     | —       | Which kind of value the field takes, and how users choose it.                                                                                                                                         |
| `presets?`      | `readonly FilterBarDatePreset[]`                   | —       | Ranges users pick with one press, such as the last 7 days. A custom range follows them.                                                                                                               |
| `min?`          | `Date`                                             | —       | The earliest day a custom range can start on.                                                                                                                                                         |
| `max?`          | `Date`                                             | —       | The latest day a custom range can end on.                                                                                                                                                             |

### FilterBarCustomField

| Property        | Type                                                            | Default | Description                                                                                                                                                                                           |
| --------------- | --------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`          | `string`                                                        | —       | The field's key in the value.                                                                                                                                                                         |
| `label`         | `string`                                                        | —       | The field's name, shown in the menu and on its chip.                                                                                                                                                  |
| `icon?`         | `React.ReactNode`                                               | —       | Shown before the label in the menu.                                                                                                                                                                   |
| `param?`        | `string`                                                        | —       | The search param the URL helpers read and write the field's value as. Defaults to `name`.                                                                                                             |
| `persistent?`   | `boolean`                                                       | —       | Keeps the field's chip in the bar, ahead of the others, even without a value, when it shows the `any` label. The chip has no remove button.                                                           |
| `defaultValue?` | `Value`                                                         | —       | The value the field returns to when the filters are cleared. An uncontrolled `FilterBar` without a `defaultValue` of its own also starts with it. A persistent field with a default can't be emptied. |
| `readOnly?`     | `boolean`                                                       | —       | Shows the field's value as a chip that can't be changed or removed, such as context the page sets. The field is left out of the menu, the URL and clearing.                                           |
| `suggestion?`   | `Value`                                                         | —       | A value to suggest while the field has none. It shows as a dashed chip, which applies the value when pressed.                                                                                         |
| `type`          | `"custom"`                                                      | —       | Which kind of value the field takes, and how users choose it.                                                                                                                                         |
| `renderEditor`  | `(props: FilterBarCustomEditorProps<Value>) => React.ReactNode` | —       | Renders the field's editor in the menu. It receives the field's value, a function that sets it, and one that closes the menu.                                                                         |
| `formatValue`   | `(value: Value) => string`                                      | —       | Returns the text the chip and the menu show for the value.                                                                                                                                            |
| `toParam?`      | `((value: Value) => string)`                                    | —       | Writes the value as a search param for the URL helpers. They skip the field unless it has both `toParam` and `fromParam`.                                                                             |
| `fromParam?`    | `((param: string) => Value \| undefined)`                       | —       | Reads the value from a search param for the URL helpers. Return `undefined` for a param that isn't valid.                                                                                             |

### FilterBarCustomEditorProps

What a custom field's `renderEditor` receives.

| Prop            | Type                                                 | Default | Description                                                                                                                                                |
| --------------- | ---------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`         | `Value \| undefined`                                 | —       | The field's value, or `undefined` while it has none.                                                                                                       |
| `onValueChange` | `(value: Value \| undefined, event?: Event) => void` | —       | Sets the field's value. Pass `undefined` to remove the filter, and the event that caused the change, if there is one, for `onValueChange`'s event details. |
| `close`         | `() => void`                                         | —       | Closes the menu.                                                                                                                                           |

### FilterBarDatePreset

| Property | Type                              | Default | Description                                                                                                         |
| -------- | --------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `value`  | `string`                          | —       | Identifies the preset in the value and the URL.                                                                     |
| `label`  | `string`                          | —       | The preset's text in the menu and on the chip.                                                                      |
| `range`  | `() => { from: Date; to: Date; }` | —       | Returns the range the preset stands for. It runs when someone chooses the preset, and when the URL helpers read it. |

### FilterBarDateRange

A `date-range` field's value.

| Property  | Type     | Default | Description                                                                                                                                             |
| --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `from`    | `Date`   | —       | The first day of the range, at local midnight.                                                                                                          |
| `to`      | `Date`   | —       | The last day of the range, at local midnight. The range includes the whole day, so compare a date with `to` by day, or against the next day's midnight. |
| `preset?` | `string` | —       | The `value` of the preset the range came from, if it came from one.                                                                                     |

### FilterBarLabels

`labels` takes any of these, and keeps the English default for the rest.

| Property              | Type                                         | Default                                            | Description                                                                                                                                                            |
| --------------------- | -------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `group?`              | `string`                                     | `"Filters"`                                        | The accessible name of the group that holds the bar.                                                                                                                   |
| `fieldsPlaceholder?`  | `string`                                     | `"Filter by…"`                                     | The placeholder of the search input in the list of fields, which also names the menu.                                                                                  |
| `optionsPlaceholder?` | `string`                                     | `"Search…"`                                        | The placeholder of the search input in a field's options.                                                                                                              |
| `textPlaceholder?`    | `string`                                     | `"Type a value…"`                                  | The placeholder of a `text` field's input.                                                                                                                             |
| `empty?`              | `string`                                     | `"No results."`                                    | What a list shows when nothing matches the search.                                                                                                                     |
| `loading?`            | `string`                                     | `"Loading…"`                                       | What a list shows while it loads options.                                                                                                                              |
| `loadError?`          | `string`                                     | `"Couldn’t load options."`                         | What a list shows when `loadOptions` fails.                                                                                                                            |
| `back?`               | `string`                                     | `"Back"`                                           | The accessible name of the button that goes back to the list of fields, or from a calendar to a date field's presets.                                                  |
| `remove?`             | `((field: string, value: string) => string)` | `` (field, value) => `Remove ${field} ${value}` `` | The accessible name of a chip's remove button, given the field's label and the value's text.                                                                           |
| `any?`                | `string`                                     | `"Any"`                                            | The value a persistent field's chip shows without a value, and the option that clears it.                                                                              |
| `customRange?`        | `string`                                     | `"Custom range…"`                                  | The option that opens a calendar to pick a custom range.                                                                                                               |
| `apply?`              | `string`                                     | `"Apply"`                                          | The button that applies a `text` field's value.                                                                                                                        |
| `applySuggestion?`    | `((field: string, value: string) => string)` | `` (field, value) => `Add ${field} ${value}` ``    | The accessible name of a suggested chip, given the field's label and the suggested value's text.                                                                       |
| `added?`              | `((field: string) => string)`                | `` (field) => `${field} filter added` ``           | What screen readers announce when a filter is added, given its field's label.                                                                                          |
| `removed?`            | `((field: string) => string)`                | `` (field) => `${field} filter removed` ``         | What screen readers announce when a filter is removed, given its field's label.                                                                                        |
| `changed?`            | `((field: string, value: string) => string)` | `` (field, value) => `${field}: ${value}` ``       | What screen readers announce when an option chosen from the menu's search changes a filter that was already applied, given the field's label and the new value's text. |
| `cleared?`            | `string`                                     | `"Filters cleared"`                                | What screen readers announce when the filters are cleared.                                                                                                             |
