React Faceted Filter Sidebar

Copy Page

The faceting engine on its own, not bolted to a table. Parametric Search bundles an Advanced Table and Resource Library bundles a card grid; this owns only the facets and hands the filtered items back through a render prop, so the same sidebar can drive a table, a card grid, a map, or anything you can render from an array.

Installation

Props

Four facet kinds, one engine

A FacetDef is a discriminated union, so each kind carries exactly the config it needs and TypeScript narrows on kind:

• checkbox — multi-select; within a facet the selections are OR-ed. Give an accessor returning a string or a string[] for multi-valued rows like tags. Options are derived from the data unless you pass them.
• radio — single-select, for mutually exclusive facets like lifecycle. Selecting a second value replaces the first.
• range — numeric min/max, committed on blur or Enter, with an optional unit.
• toggle — a boolean gate driven by a predicate, for "in stock" or "RoHS compliant".

Long lists get two affordances a facet sidebar lives or dies on: searchable adds an option-search box, and maxVisible collapses to the first N options behind a "show more". Any facet can be collapsible.

Counts are leave-one-out, and they never lie

The number beside each option is the result count you'd get if you selected it — computed against every other active facet but not this one. That is the distributor convention, and it is the correct one: if selecting a value within a facet narrowed its own options' counts, every count would drop to reflect a choice you haven't made yet, and the ones you didn't pick would misleadingly read zero. Options that would yield nothing dim to signal a dead end without removing them, so the shape of the data stays visible.

Decoupled by construction

The component renders the sidebar, the applied-filter chips, a live result count, and a mobile drawer — and then calls children(filtered) with the surviving items. It never renders your results, which is the point: the demo drives a plain card grid, but the same instance would drive a table or a <canvas> map without changing a line of the filter code. State can be left uncontrolled, or lifted via value / onChange to sync with the URL so a filtered view is shareable. On mobile the whole sidebar folds into a drawer behind a Filters button that carries a badge with the active-facet count, because a filter panel that eats the screen on a phone is a filter panel nobody opens.