Skip to content
ilinxa/pro-ui

Filter Bar

alphav0.3.0

Composite filter bar — search, category pills, date-range picker, and results count, each independently controlled or hidden.

Category: FormsUpdated: 2026-10-26Created: 2026-05-02Author: ilinxa

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

Initialize shadcn (once per project)Seeds lib/utils.ts and components.json. Skip if you've already used any shadcn component.
pnpm dlx shadcn@latest init
Install the component
pnpm dlx shadcn@latest add @ilinxa/filter-bar

Add -fixtures for dummy data:

pnpm dlx shadcn@latest add @ilinxa/filter-bar-fixtures

CLI 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

demo.tsxtsx
"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=&quot;left&quot; + locale=&quot;tr&quot; (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=&quot;right&quot; (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

  • onChange no 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, pass emitInitialChange: 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. Pass locale to 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" 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.

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

Tags

filter-barformsfiltersearchdate-rangemigration

Dependencies

shadcn primitives: input, button, popover, calendar
npm peer deps: lucide-react@^1.11.0, react-day-picker@^9.14.0