Filter Bar

When to use

Reach for FilterBar in any browse-and-filter UI: news landing pages, blog archives, doc indexes, file browsers, dashboards, e-commerce category pages. Three sub-controls in one bar — search + category chips + date-range — plus an optional results count. Each is independently controlled-or-uncontrolled.

Minimal example

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

<FilterBar
  categories={[
    { value: "tech", label: "Technology" },
    { value: "design", label: "Design" },
  ]}
  resultsCount={42}
/>;

With no controlled props, all 3 sub-controls run uncontrolled with a 250ms debounce on the search. The bar emits no events but the UI works for visual demos.

Controlled (the common case)

const [filters, setFilters] = useState<FilterBarValue>({
  search: "",
  category: null,
  dateRange: { from: undefined, to: undefined },
});

<FilterBar
  categories={categories}
  search={filters.search}
  onSearchChange={(s) => setFilters((v) => ({ ...v, search: s }))}
  category={filters.category}
  onCategoryChange={(c) => setFilters((v) => ({ ...v, category: c }))}
  dateRange={filters.dateRange}
  onDateRangeChange={(d) => setFilters((v) => ({ ...v, dateRange: d }))}
  resultsCount={filteredItems.length}
/>;

Or use the combined onChange emitter:

<FilterBar
  categories={categories}
  onChange={({ search, category, dateRange }) => {
    setFilters({ search, category, dateRange });
  }}
/>;

Hide sub-controls

<FilterBar categories={categories} hideDateRange />
<FilterBar hideCategories hideSearch />

Localization

<FilterBar
  categories={categories}
  labels={{
    searchPlaceholder: "Haber ara...",
    allLabel: "Tümü",
    dateButtonText: "Tarih Filtrele",
    clearDateText: "Tarihi Temizle",
    resultsCountText: (n) => `${n} haber bulundu`,
  }}
  formatDateRange={({ from, to }) => {
    const fmt = new Intl.DateTimeFormat("tr-TR", { day: "numeric", month: "short" });
    return `${fmt.format(from)} - ${fmt.format(to)}`;
  }}
/>;

Search debounce

In uncontrolled mode, search is debounced 250ms by default — set searchDebounceMs={0} for instant or increase for slower-changing dropdowns. In controlled mode the debounce is bypassed; consumer's onChange fires on every keystroke. Debounce yourself if you need it.

Accessibility

• Search input is wrapped in <div role="search"> for landmark.
• Chip row uses role="group" with aria-label; each chip is a real <button> with aria-pressed.
• Results count has aria-live="polite" so updates announce.
• Clear-date button has aria-label from labels.clearDateLabel.
• Date Popover inherits ARIA from shadcn primitives.