Filter Bar

Install

pnpm dlx shadcn@latest add @vegastack/filter-bar

Usage

import { FilterBar } from "@/components/ui/filter-bar";

<FilterBar
  aria-label="Task filters"
  filters={[
    {
      id: "status",
      label: "Status",
      value: "In Progress",
      onRemove: removeStatus,
    },
  ]}
  addFilters={[{ id: "priority", label: "Priority" }]}
  onAddFilter={(id) => openFilter(id)}
  search={{ value: query, onValueChange: setQuery }}
/>;

FilterBar is presentational — it never holds filter state. You own the array of active filters and update it in each filter's onRemove; you decide what an addFilters option does in onAddFilter; and search is a controlled value / onValueChange pair.

Anatomy

Filter Bar is a compound component. Every exported part, with the data-slot it renders (generated from the canonical source):

Examples

Anatomy

The bar lays out three regions left-to-right, all built from VegaStack primitives:

<FilterBar
  filters={[/* … */]} // → one removable <FilterChip> per active filter
  addFilters={[/* … */]} // → an "Add filter" <DropdownMenu> (Button trigger)
  onAddFilter={(id) => {}}
  search={{ value, onValueChange }} // → a trailing search <Input type="search">
  trailing={/* e.g. a "Clear all" Button */}
/>

• FilterBar — the container (data-slot="filter-bar", role="group"). A wrapping flex row that reflows its children when space is tight. It defaults to aria-label="Filters"; pass aria-label or aria-labelledby when the surrounding UI needs a more specific group name.
• FilterChip — one active filter (data-slot="filter-chip"): an optional leading icon, a muted label, an optional emphasized value beside it, and a trailing × Button that fires onRemove. Rendered once per filters entry, and also exported standalone for custom layouts.
• Add filter — a DropdownMenu whose trigger is a dashed-outline Button (data-slot="filter-bar-add"). Built from the declarative addFilters array, or replaced wholesale with the addFilterMenu slot for submenus / multi-select.
• Search — a controlled Input of type="search" (data-slot="filter-bar-search"), pushed to the trailing edge. Omit search to hide it.

Filter compositions

With search

A query input is pushed to the trailing edge alongside the chips and the "Add filter" menu.

Empty

With no active filters, only the "Add filter" menu (and search, if enabled) remain.

Presence-only chip & disabled option

A filter without a value renders as a label-only presence chip (the filter is simply on or off). The "Add filter" menu here also carries a disabled option — it stays visible but is skipped by arrow-key navigation.

Custom add-filter menu

Pass addFilterMenu to replace the declarative menu wholesale with any DropdownMenu tree — here a multi-select checkbox group. addFilterMenu takes precedence over addFilters; supply the whole menu including its trigger.

Standalone chips

FilterChip is exported on its own for custom toolbars. It is the Chip primitive at the standalone (md, 32px) tier, so it lines up with the Buttons and Inputs beside it. The example shows an active chip (promoted to the surface-2 selection rung), a plain active={false} presence chip on the rest fill, and a value-less chip.

Scope (presentational core)

FilterBar is a presentational primitive (Model A — the component owns rendering; your app owns the filter state). It renders the chips, the add-filter menu, the search field, and a trailing slot. Stateful/data behavior from the platform demo is deliberately consumer-owned, not built-in (a recorded scope decision — requirements §12), and each has a composition path:

• Active-filter state — you hold the filter model and map it to filters; the component is controlled.
• Clear-all — compose a button into trailing:

  <FilterBar
    filters={chips}
    trailing={
      active.length > 0 && (
        <Button variant="ghost" size="sm" onClick={clearAll}>
          Clear all
        </Button>
      )
    }
  />

• Editable chip popovers — wrap a FilterChip in a Popover to edit a filter's value in place.
• AI-suggested filters — an app/data concern (out of the DS primitive); render your suggestions into the add-filter menu or trailing.

The component matrix marks FilterBar complete for this presentational-core scope; the fully-stateful nested builder is FilterBuilder.

API Reference

FilterBar

FilterChip

FilterBarFilter

The shape of each entry in FilterBar's filters array — one removable chip.

FilterBarFilter

FilterBarAddOption

The shape of each entry in the declarative addFilters menu.

FilterBarAddOption

FilterBarSearch

The controlled search config passed to FilterBar.

FilterBarSearch

Accessibility

• The bar is a named role="group" ("Filters" by default) so assistive tech announces the filter controls as a single related set. Use aria-label/aria-labelledby for a more specific group name like "Task filters".
• Each chip's remove control is the shared ChipRemove: a round ghost IconButton whose REAL border box is 24×24 (WCAG 2.5.8), with an accessible name — Remove <label> filter when label is a string, overridable via FilterChip's removeLabel.
• The "Add filter" trigger is a labelled Button that opens a keyboard-navigable DropdownMenu; arrow keys move between options and Esc closes it.
• The search field always has an accessible name — it falls back to the placeholder, then Search. Provide aria-label on search for a name distinct from the placeholder.
• Every interactive part keeps a visible :focus-visible ring — never outline: none.

Do / Don't