Xzero UI
Pro library
ComponentsFilter toolbar

Filter toolbar

Keep collection filters close and easy to reset.

$ pnpm dlx shadcn@4.23.0 add @xzero-ui/filter-toolbar
Live · keyboard ready

When to use

When not to use

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui/filter-toolbar

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { useState } from "react";
import { FilterToolbar, type FilterChip } from "@/components/xzero/filter-toolbar/filter-toolbar";

const fields = [
  { id: "status", label: "Status", options: ["Open", "Closed"] },
  { id: "owner", label: "Owner", options: ["Maya", "Leo"] },
];

export function IssueFilters() {
  const [filters, setFilters] = useState<FilterChip[]>([]);
  return (
    <FilterToolbar
      filters={filters}
      onRemove={id => setFilters(f => f.filter(x => x.id !== id))}
      onClearAll={() => setFilters([])}
      addFilter={{ fields, onAdd: chip => setFilters(f => [...f.filter(x => x.id !== chip.id), chip]) }}
    />
  );
}

API reference

FilterToolbar

A row of removable filter chips with Clear all and an optional Add filter menu.

PropTypeDefaultDescription
filters (required){ id: string; label: string; value?: string }[]–Applied filters, shown as chips.
onRemove (required)(id: string) => void–Called when a chip's remove button is pressed.
onClearAll() => void–Called by Clear all, which appears while any filter is applied.
addFilter{ fields: FilterField[]; onAdd: (filter: FilterChip, field: FilterField) => void; label?: string; align?: "start" | "end" }–Adds an Add filter trigger that opens a two step field and value menu.
childrenReactNode–Extra actions next to the Add filter trigger.
labelstring"Active filters"Accessible name for the toolbar group.

FilterMenu

The Add filter trigger and its two step menu, usable on its own.

PropTypeDefaultDescription
fields (required){ id: string; label: string; icon?: ReactNode; options: (string | { value: string; label?: string; hint?: string | number; icon?: ReactNode })[] }[]–Filterable fields and their values.
onSelect (required)(filter: FilterChip, field: FilterField) => void–Receives a chip whose id is the field id, so a second pick for a field replaces the first.
activeFilterChip[][]Applied filters, used to mark current values.
labelstring"Add filter"Trigger text.
align"start" | "end""end"Trigger edge the panel lines up with. Flips when there is no room.

Keyboard interactions

KeysAction
ArrowDown / ArrowUpOn the trigger, opens the menu at the first or last item; inside, moves between items.
Home / EndMoves to the first or last menu item.
ArrowRight / ArrowLeftDrills into a field's values, or goes back to fields.
LettersTypeahead jumps to the matching item.
EscapeCloses the menu and returns focus to the trigger.

Accessibility

Motion

Responsive behavior

Performance

Notes for AI

Also in tables

Guidance for AI tools

Filter toolbar: Keep collection filters close and easy to reset. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt

Browse all components