Filters

The filter bar shows each active filter as a chip that reads like a sentence ("Status is In progress"). Use it on list and table views where people narrow results by several conditions at once.

For a single dropdown tied to a form field, use Combobox instead.

Preview#

"use client";
 
import * as React from "react";
import {
  Filters,
  createFilter,

Installation#

npxnpx shadcn@latest add @cubby-ui/filters

Usage#

import {
  Filters,
  createFilter,
  type FilterField,
  type FilterValue,
} from "@/components/ui/cubby-ui/filters/filters";

<Filters />

Composition#

Filters                  (FiltersProvider + FiltersBar)
├── FilterChips
│   └── FilterChip
│       ├── FilterChipField
│       ├── FilterChipOperator
│       ├── FilterChipValue
│       └── FilterChipRemove
└── FilterActions
    ├── FilterActionsAdd
    └── FilterActionsClear

Features#

• Picking a field in the add menu slides to its values, so a chip appears only once it has one.
• Searching the menu also matches values across fields: type "done" to add "Status is Done" in one step.
• Chips that outgrow the row scroll sideways, and the add and clear buttons stay in view.
• A chip still waiting on its value shows a dashed edge and doesn't count as active.

Examples#

Field types#

Use type to pick each field's value control.

"use client";
 
import * as React from "react";
import {
  Filters,
  type FilterField,

Operators#

Use operators to replace a field's operators or disabledOperators to hide some; each operator's shape picks its control.

"use client";
 
import * as React from "react";
import {
  Filters,
  createFilter,

Multiselect#

Use maxSelections to cap the picks and labels.selectedCount to word the "3 selected" summary.

"use client";
 
import * as React from "react";
import {
  Filters,
  createFilter,

Prefix and suffix#

Use prefix and suffix on text and number fields for currency, units, or symbols.

"use client";
 
import * as React from "react";
import {
  Filters,
  createFilter,

Controlled#

Pass value and onValueChange to own the filters; FilterActiveCount shows how many are active.

[]

"use client";
 
import * as React from "react";
import {
  Filters,
  FilterActiveCount,

Overflow#

Chips scroll sideways once they outgrow the row; set overflow="wrap" to flow them onto new rows instead.

"use client";
 
import * as React from "react";
import {
  Filters,
  createFilter,

Sizes#

Use size to set the height of every chip in the bar.

"use client";
 
import * as React from "react";
import {
  Filters,
  createFilter,

Variants#

Use variant to pick the shell the chips and the add button sit on.

"use client";
 
import * as React from "react";
import {
  Filters,
  createFilter,

A filter with no value yet shows a dashed border on every variant.

Keyboard shortcut#

Set shortcut to a key that opens the add menu, ignored while typing or while a popup is open.

"use client";
 
import * as React from "react";
import {
  Filters,
  type FilterField,

Empty state#

Pass open and onOpenChange to FilterActionsAdd so a button outside the bar can open the add menu.

"use client";
 
import * as React from "react";
import { Button } from "@/components/ui/cubby-ui/button";
import {
  FilterActions,

Manual layout#

Pass children to arrange the parts yourself.

"use client";
 
import * as React from "react";
import {
  Filters,
  FilterActiveCount,

URL state with nuqs#

Wire value and onValueChange to nuqs to keep the filters in ?filters=, parsed back through asFilterValues.

"use client";
 
import * as React from "react";
import { NuqsAdapter } from "nuqs/adapters/next/app";
import { useQueryState } from "nuqs";
import {

Server-side filtering#

onValueChange fires on every keystroke, so send only complete filters and let typing settle before you fetch.

import { isFilterComplete } from "@/components/ui/cubby-ui/filters/filters";
 
const query = React.useDeferredValue(
  value.filter((filter) => {
    const field = fields.find((f) => f.id === filter.field);
    return field !== undefined && isFilterComplete(field, filter);
  }),
);

State outside the bar#

Use FiltersProvider and FiltersBar separately when UI outside the row (a results count, saved views) reads the same state through useFilters.

<FiltersProvider fields={fields} value={value} onValueChange={setValue}>
  <PageHeader>
    <FilterSummary />
  </PageHeader>
  <FiltersBar />
</FiltersProvider>

Accessibility#

Keyboard#

Screen readers#

• Each chip is a group named after its filter, such as "Status is In progress", and each segment names itself.
• A hidden status region announces adds, removes, and clears, since focus lands elsewhere.
• The add menu flags an unreadable number with an "Enter a number" hint tied to the input.

Custom chips#

Keep the filter-chip, filter-chip-remove, and filter-add slots on custom parts; keyboard removal and focus handoff look for them.

API Reference#

Filters composes Cubby UI primitives and has no Base UI root of its own.

Props#

Filters#

FiltersProvider and FiltersBar in one. shortcut, overflow, and div props go to the bar; the rest go to the provider.

FilterAddButton#

The add button and its menu. FilterActionsAdd is the same menu as a segment of FilterActions, and takes these props too.

FilterChip#

Other parts#

Handlers you pass to a part (onClick, onKeyDown, onBlur) run first; call event.preventDefault() to skip the built-in behavior.

Hooks#

Types#

FilterField#

A union keyed on type. Every field has id, label, and optional icon, operators, and disabledOperators.

renderValue renders as its own component, so it can use hooks. formatValue turns the value into text for the chip's name; strings, numbers, and booleans work without it.

FilterValue#

interface FilterValue {
  id: string;
  field: string;
  operator: string;
  value: unknown;
}

Helpers#