Filter Bar
alphav0.3.0Composite filter bar — search, category pills, date-range picker, and results count, each independently controlled or hidden.
Context
Browse-and-filter UI workhorse: news, blogs, docs, dashboards, e-commerce facets. Three sub-controls (search / chips / date-range) with independent state, plus a combined onChange emitting `{ search, category, dateRange }`. Search debounces 250ms in uncontrolled mode. Date-range Popover composes a lazily loaded shadcn Calendar (react-day-picker; date-fns comes with it). Migration origin: kasder kas-social-front-v0 NewsMagazineGrid.tsx header section. Composed by `magazine-layout` in the news-domain family.
Installation
pnpm dlx shadcn@latest initpnpm dlx shadcn@latest add @ilinxa/filter-barAdd -fixtures for dummy data:
pnpm dlx shadcn@latest add @ilinxa/filter-bar-fixturesCLI can't resolve @ilinxa? The namespace is listed in the official shadcn registry directory, so current CLIs need no configuration. If yours can't resolve it (older or pinned versions, self-hosted mirrors), register it manually in components.json:
"registries": {
"@ilinxa": "https://ui.ilinxa.com/r/{name}.json"
}Preview
42 items found
Demo source
"use client"; import { useState } from "react";import { SlidersHorizontal } from "lucide-react";import { Tabs, TabsContent, TabsTrigger } from "@/components/ui/tabs";import { SwipeTabsList } from "@/components/site/swipe-tabs-list";import { ar, tr } from "date-fns/locale";import { FilterBar } from "./filter-bar";import { DUMMY_CATEGORIES_AR, DUMMY_CATEGORIES_EN, DUMMY_LABELS_AR, DUMMY_LABELS_TR, formatDateRangeTR,} from "./dummy-data";import type { FilterBarValue } from "./types"; function AccessoryButton({ label }: { label: string }) { return ( <button type="button" aria-label={label} className="rounded-md p-2 text-muted-foreground hover:bg-muted hover:text-foreground" > <SlidersHorizontal aria-hidden="true" className="h-4 w-4" /> </button> );} export default function FilterBarDemo() { const [controlledValue, setControlledValue] = useState<FilterBarValue>({ search: "", category: null, dateRange: { from: undefined, to: undefined }, }); return ( <Tabs defaultValue="basic" className="w-full"> <SwipeTabsList> <TabsTrigger value="basic">Basic</TabsTrigger> <TabsTrigger value="controlled">Controlled</TabsTrigger> <TabsTrigger value="partial">Partial usage</TabsTrigger> <TabsTrigger value="i18n">Localized</TabsTrigger> <TabsTrigger value="options">Options</TabsTrigger> <TabsTrigger value="rtl">RTL</TabsTrigger> </SwipeTabsList> <TabsContent value="basic" className="mt-6"> <FilterBar categories={DUMMY_CATEGORIES_EN} resultsCount={42} /> </TabsContent> <TabsContent value="controlled" className="mt-6 space-y-4"> <FilterBar categories={DUMMY_CATEGORIES_EN} search={controlledValue.search} onSearchChange={(search) => setControlledValue((v) => ({ ...v, search })) } category={controlledValue.category} onCategoryChange={(category) => setControlledValue((v) => ({ ...v, category })) } dateRange={controlledValue.dateRange} onDateRangeChange={(dateRange) => setControlledValue((v) => ({ ...v, dateRange })) } resultsCount={42} /> <pre className="rounded-md border border-border bg-muted p-4 text-xs"> {JSON.stringify( { search: controlledValue.search, category: controlledValue.category, dateRange: { from: controlledValue.dateRange.from?.toISOString(), to: controlledValue.dateRange.to?.toISOString(), }, }, null, 2, )} </pre> </TabsContent> <TabsContent value="partial" className="mt-6 space-y-8"> <div> <p className="mb-2 text-sm font-semibold text-foreground"> Search + chips only (date hidden) </p> <FilterBar categories={DUMMY_CATEGORIES_EN} hideDateRange resultsCount={42} /> </div> <div> <p className="mb-2 text-sm font-semibold text-foreground"> Search + date only (categories hidden) </p> <FilterBar hideCategories resultsCount={42} /> </div> </TabsContent> <TabsContent value="i18n" className="mt-6"> <FilterBar categories={DUMMY_CATEGORIES_EN} labels={DUMMY_LABELS_TR} calendarLocale={tr} formatDateRange={formatDateRangeTR} resultsCount={12} /> </TabsContent> <TabsContent value="options" className="mt-6 space-y-8"> <div> <p className="mb-2 text-sm font-semibold text-foreground"> searchAccessory + align="left" + locale="tr" (dates and grouped count) </p> <FilterBar categories={DUMMY_CATEGORIES_EN} align="left" locale="tr" defaultDateRange={{ from: new Date(2026, 9, 5), to: new Date(2026, 9, 19) }} resultsCount={1234} searchAccessory={<AccessoryButton label="Search options" />} /> </div> <div> <p className="mb-2 text-sm font-semibold text-foreground"> align="right" (the chip row follows it too) </p> <FilterBar categories={DUMMY_CATEGORIES_EN} align="right" resultsCount={1} /> </div> </TabsContent> <TabsContent value="rtl" className="mt-6"> <div dir="rtl" lang="ar"> <FilterBar categories={DUMMY_CATEGORIES_AR} labels={DUMMY_LABELS_AR} locale="ar" calendarLocale={ar} align="left" resultsCount={12} searchAccessory={<AccessoryButton label="خيارات البحث" />} /> </div> </TabsContent> </Tabs> );} Usage
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. Add onChange to hear about each change.
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)}`;
}}
/>;Locale and time zone
import { tr } from "date-fns/locale";
<FilterBar
categories={categories}
locale="tr" // default date formats + grouped count
timeZone="Europe/Istanbul"
calendarLocale={tr} // month and day names; you import it, we don't bundle locales
resultsCount={1234}
/>;locale defaults to "en"; an invalid tag falls back to "en". The count is formatted with Intl.NumberFormat only when you pass locale. The default count text is "1 item found" / "{n} items found"; translate it through labels.resultsCountText. formatDate / formatDateRange still override the defaults. A well-formed tag the runtime has no data for also falls back to "en". timeZonereaches both the default formatting and the calendar, so the day picked is the day shown. The default time zone is the runtime's, so when you server render a preset date range, pass timeZone so server and client agree.
dir="rtl" sets the direction of the calendar popover (default: resolved from the nearest [dir]); pass calendarLocale for localized month and day names. If the calendar chunk fails to load, a short message with a retry button shows instead (labels.calendarLoadErrorText / labels.calendarRetryText).
Alignment and the search accessory
<FilterBar
categories={categories}
align="left" // search, filter row and wrapped chip lines
searchAccessory={<FilterMenuButton />} // inline end of the search field, after the input in tab order
/>;Search debounce
In uncontrolled mode, search is debounced 250ms by default (searchDebounceMs) and emits one onChange per commit. In controlled mode onSearchChange fires on every keystroke unless you set debounceControlledSearch: the input then keeps a local echo and commits after searchDebounceMs. The searchprop wins whenever it changes to a value that is not one of the field's own commits (a URL change, a reset): the field resyncs to it, and a host that adopts commits late is fine. While a commit is pending the field shows the user's typing, and a host that never adopts a commit leaves the field showing the typed text until the prop next changes. Using the chips or the date range while a search commit is pending commits the visible text first, so that interaction's single onChange carries it.
Migrating to 0.3.0
onChangeno longer fires on mount, when its own identity changes, or when a controlled prop changes from outside. It fires once per user interaction. Delete any "skip the first call" ref. To keep the old start, passemitInitialChange: one call on mount with the initial value.- The default date locale is now
"en"instead of the browser's language, so the server and client render the same text. Passlocaleto get another one. - The count reads "1 item found" for one result (it was "1 items found").
- The calendar loads when the date popover first opens; it never loads with
hideDateRange.
Accessibility
- Search input is wrapped in
<div role="search">for landmark. - Chip row uses
role="group"witharia-label; each chip is a real<button>witharia-pressed. - Results count has
aria-live="polite"so updates announce. - Clear-date button has
aria-labelfromlabels.clearDateLabel. - Date Popover inherits ARIA from shadcn primitives.
Features
- 3 sub-controls in one bar — search input + category pill row + date-range Popover
- Independently controlled-or-uncontrolled per sub-control
- Combined `onChange` emits the merged `{ search, category, dateRange }` once per user interaction — never on mount, never when a callback identity or a controlled prop changes; `emitInitialChange` opts in to one mount call
- Uncontrolled search debounces 250ms (configurable) and emits one `onChange` per commit; `debounceControlledSearch` gives controlled search the same debounce with a local echo and a resync when the prop moves
- Sub-control hide flags — `hideSearch` / `hideCategories` / `hideDateRange` for partial usage
- "All" sentinel chip clears the category filter (maps to null internally)
- Optional results count with `aria-live='polite'` announcements; default text is "1 item found" / "{n} items found"
- i18n via `labels` prop, `locale` (default "en") + `timeZone` for the default date formatting, and `formatDate` / `formatDateRange` callbacks
- `calendarLocale` forwards a date-fns Locale (host-imported) and `dir` to the calendar; `dir` otherwise resolves from the nearest [dir]
- Layout `align` (left | center | right; default center) aligns the search, the filter row and the chip row
- `searchAccessory` slot at the inline end of the search field, after the input in tab order
- Calendar is lazy-loaded: react-day-picker + date-fns load only when the date popover first opens (never with `hideDateRange`)
- Native `<button aria-pressed>` chips; `role=group` on chip row; `role=search` on the search wrapper
- React.memo wrapped