# Filter bar

> Search, saved views and filter chips with an Add filter builder that steps through field, operator and value; chips spring in, the bar closes the gap and the result count rolls.

- Collection: Components
- Tier: pro
- Docs: https://geturui.com/docs/filter-bar
- Install: `npx shadcn@latest add @geturui-pro/filter-bar`
- Dependencies: motion, lucide-react

## Usage

```tsx
import { FilterBar, applyFilters, type Filter, type FilterField } from "@/components/ui/filter-bar";

const fields: FilterField[] = [
  { key: "status", label: "Status", type: "select", options: [{ value: "active", label: "Active" }, { value: "paused", label: "Paused" }] },
  { key: "owner", label: "Owner", type: "text" },
  { key: "updated", label: "Updated", type: "date" },
];

export function ProjectFilters({ projects }: { projects: { status: string; owner: string; updated: string }[] }) {
  const [filters, setFilters] = React.useState<Filter[]>([]);
  const rows = applyFilters(projects, filters, fields, (p, key) => p[key as keyof typeof p]);
  return <FilterBar fields={fields} filters={filters} onFiltersChange={setFilters} resultCount={rows.length} resultLabel="projects" />;
}
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| fields | `FilterField[]` | — | { key, label, type: "text" | "select" | "date", options?, placeholder? }. |
| filters / defaultFilters / onFiltersChange | `Filter[]` | — | { id, field, operator, value: string[] }. Date values are a relative token ("7d") or an ISO day. |
| query / defaultQuery / onQueryChange | `string` | — | Search text. Escape clears it. |
| views / view / defaultView / onViewChange | `SavedView[] / string` | — | Segmented saved views; picking one replaces filters and query. A dot marks an edited view. |
| resultCount / resultLabel | `number / string` | — | Rolling count announced politely, e.g. "6 projects". |
| actions | `ReactNode` | — | Right-aligned slot on the views row. |
| searchPlaceholder | `string` | "Search" | Placeholder and accessible name of the search box. |
| today | `Date` | — | Reference day for relative date filters. Omit to read the clock after hydration. |
| applyFilters / matchesFilter / describeFilter | `functions` | — | Run the filter model on your rows, or turn a filter into a sentence. |

## Accessibility

- Each chip is a button named with the full sentence ("Status is Active. Edit filter"); Backspace or Delete removes it, and its × is labelled.
- Builder steps are listboxes with arrow, Home and End keys; focus moves to the first option on each step.
- Saved views are a radiogroup with roving focus and arrow keys.
- The result count lives in a polite live region; chip and step transitions become fades under reduced motion.

## Source

Pro item — send `Authorization: Bearer <registry token>` to include the source.