Filter panel React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Filter panel is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import FilterPanel from @/components/ui/filter-panel.

import { useState } from "react"
import { Truck } from "lucide-react"
import { FilterPanel, type FilterDef, type FilterValues } from "@/components/ui/filter-panel"

const filters: FilterDef[] = [
  { type: "price", id: "price", label: "Price", min: 0, max: 1800, presets: [{ min: null, max: 100 }, { min: 100, max: 300 }] },
  {
    type: "chips",
    id: "condition",
    label: "Condition",
    options: [
      { value: "new", label: "New", count: 310 },
      { value: "used", label: "Used", count: 843 },
      { value: "parts", label: "For parts", count: 87 },
    ],
  },
  {
    type: "checkbox",
    id: "brand",
    label: "Brand",
    options: [
      { value: "apple", label: "Apple", count: 312 },
      { value: "samsung", label: "Samsung", count: 287 },
      { value: "xiaomi", label: "Xiaomi", count: 164 },
    ],
  },
  { type: "toggle", id: "delivery", label: "Delivery only", icon: <Truck /> },
]

export function PhoneFilters({ count }: { count: (values: FilterValues) => Promise<number> }) {
  const [values, setValues] = useState<FilterValues>({})
  return (
    <div className="flex flex-col gap-4 lg:flex-row lg:items-start">
      <FilterPanel
        filters={filters}
        value={values}
        onValueChange={setValues}
        getResultCount={count}
        locale="en-US"
        className="lg:w-72 lg:shrink-0"
      />
      <main className="min-w-0 flex-1">{/* results */}</main>
    </div>
  )
}

Props

• filters*
  FilterDef[]

  The sections, in order. A union on type: category (a CategoryPicker list), price (a PriceRange over a histogram), location (a place combobox, popular places and radius chips; "My location" with onLocate), checkbox (rows with counts, a limit and "Show more", a search field past ten options), radio (with an "any" row), chips (single or multiple), range (a two-thumb slider and two number inputs with a unit), toggle (a switch row) and custom (render, describe, isActive). Every filter has an id, a label, an optional description and defaultCollapsed. Unknown types are skipped with a warning in development.

• value
  FilterValues

  The committed filters, keyed by filter id: category and radio a string, price and range [min, max] with null for an open end, location { place, radius }, checkbox and chips string[], toggle true. Inactive filters leave the object; keys of filters not in the list are kept.

• defaultValue
  FilterValues

  The starting filters while uncontrolled. Defaults to {}.

• onValueChange
  (values: FilterValues) => void

  The sidebar in instant mode calls it on every commit (a slider release, a toggle, a pick, never per keystroke); the sheet and apply mode call it on the Apply button; chips and Clear all call it at once in the sidebar.

• modedefault "auto"
  "auto" | "sidebar" | "sheet"

  auto shows the sidebar from the breakpoint up and the Filters button with a bottom sheet below it (switched with CSS, so the server HTML is right). sidebar always shows the sidebar; sheet always shows the button, with a side panel on desktop.

• breakpointdefault "lg"
  "md" | "lg"

  Where auto switches from the sheet to the sidebar: 768px or 1024px. Crossing it with the sheet open closes the sheet.

• applyModedefault "instant"
  "instant" | "apply"

  The sidebar's behavior: instant commits each change, apply keeps a draft until the Apply button in its footer. The sheet always keeps a draft.

• getResultCount
  (values: FilterValues) => (number | Promise<number>)

  Counts the sheet's draft for its button, 250ms after the last change (the first count of an opening runs at once). A promise shows a spinner; an older answer never overwrites a newer one; a rejection falls back to the plain Show results label.

• resultCountdefault 0
  number

  A fixed count for the sheet's button when there is no getResultCount. 0 reads Show results.

• open
  boolean

  The sheet's open state, controlled. Opening copies the committed value into a draft; a value changing while it is open does not touch the draft.

• defaultOpendefault false
  boolean

  Starts with the sheet open (only where the sheet is in use: sheet mode, or auto below the breakpoint).

• onOpenChange
  (open: boolean) => void

  Called when the sheet opens or closes, by the button, a shortcut, a swipe, the backdrop or Escape.

• triggerdefault "<FilterPanelTrigger />"
  ReactNode

  Replaces the Filters button that opens the sheet (a single element that takes a ref). null renders none, so you can open the sheet from a toolbar with open and onOpenChange.

• showChipsdefault true
  boolean

  The active filters as removable chips under the title (sidebar) or at the top of the sheet.

• collapsibledefault true
  boolean

  Sections fold like an accordion. false keeps every section open under a plain heading.

• defaultExpanded
  string[]

  Filter ids open at first. Defaults to the first four sections in the sidebar and the first two in the sheet (skipping toggles and those with defaultCollapsed).

• hideEmptydefault false
  boolean

  Hides options with a count of 0 instead of showing them disabled. A picked option always stays.

• stickydefault true
  boolean

  The sidebar sticks under var(--topbar-offset, 0px) and scrolls on its own when it is taller than the screen.

• sizedefault "md"
  "sm" | "md"

  The controls inside: checkboxes, switches, sliders, fields and chips. sm suits a narrow sidebar.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  Checked boxes, picked chips, the slider ranges, the lit histogram bars, the section dots, the count badge and the Apply button.

• colordefault ""
  string

  Any CSS color; replaces the tone everywhere it paints.

• shortcutdefault ""
  string

  A key combo in mod+k notation that opens (and closes) the sheet, or jumps to the first section while the sidebar shows. The button shows it as a key hint on devices with a keyboard. None by default.

• currencydefault "USD"
  string

  ISO 4217 code for the price section, its chips and summaries.

• localedefault ""
  string

  Counts, prices and ranges (1,240 in en-US). Empty uses the UIProvider's locale, then the browser's.

• container
  HTMLElement | null

  Portal target of the sheet. Defaults to document.body.

• labels
  Partial<FilterPanelLabels>

  Every string, English by default (DEFAULT_FILTER_PANEL_LABELS): title "Filters", clearAll "Clear all", reset "Reset", apply "Apply", showResults (count, formatted), showResultsUnknown "Show results", noResults "No results, try fewer filters", any "Any", anywhere "Anywhere", radius (km) "+25 km" ("Only here" for 0), distance, myLocation "My location", showMore (count), showLess, searchOptions, noMatches, from, to, rangeFrom (value), rangeTo (value), trigger "Filters", active (count) "3 active", chips, remove, clear, cancel (the place field and its phone sheet), plus priceRange and categoryPicker labels passed through.

• classNames
  Partial<Record<"sidebar" | "header" | "chips" | "section" | "trigger" | "content" | "footer" | "apply", string>>

  Extra classes for the parts: the sidebar's aside (give it a panel look here), the headers, the chip row, each section, the Filters button, the sheet, the footers and the Apply buttons.

• className
  string

  Extra classes for the root; the page sets the sidebar's width here (lg:w-72).

Parts

FAQ

Used in

More React commerce components