Shadcn Filters
Browse 12 production-ready shadcn filter components integrating TanStack Table column filters, Zod validation, nuqs URL state persistence, react-day-picker date ranges, and i18n support. Covers field type variety, custom triggers, data grid integration, async filter mode, and size variants.
For AI Agents
Hand your agent this brief or the ReUI MCP, not a screenshot. Free to install.
When to use
- Toolbars of removable filter chips over a table or list, one field, condition and value per chip
- Nested AND and OR condition builders, hung off a trigger over a report or laid out inline
- Attribute catalogs too large or deep to list at once, and option lists paged from a server
When not to use
- A finished record table with its chip bar, paging and row actions already built: use the Filtering blocks
- Storefront product facets with price sliders, color swatches and department pills: use the Filter Sidebar blocks
- One day or span of days picked on its own, with no attribute or condition: use the Date Selector component
Agent notes
renderValue,iconand a componenteditorcount toward the schema index by presence only, so swapping one alone keeps serving the old one- A rule reaches
onQueryChangeunfinished: an emptyoperator, or avaluestill undefined or empty where itsarityis not none; skip it when compiling - Negate swaps to an operator's
inversewhere one exists and otherwise setsnegated, as onstarts_with, so a compiler must readnegated
Third-party API docs
- date-fns v4: docs
- TanStack Table v9: API reference, docs, used by 2 of 12 examples
- React DayPicker v9: API reference, docs, used by 1 of 12 examples
- input-otp v1: API reference, docs, used by 1 of 12 examples
https://web.dev.reui.io/components/filters.mdget_component("filters")npx shadcn@latest add @reui/filtersShadcn Filters: Faceted Search with TanStack and nuqs
ReUI Filters is a custom shadcn component for building filter panels that connect directly to TanStack Table's column filter API. It renders a composable set of field types: text, select, multi-select, date range, number range, and boolean toggles: validates input with Zod, and persists active filters to the URL with nuqs for shareable, bookmarkable filtered views.
12 components cover field variety, input validation, custom trigger buttons, compact and large size variants, custom control rendering, full data grid integration, async filter mode for server-side filtering, and i18n support with locale-aware labels and date formatting.
The sections below explain the architecture, why URL-persistent filters matter, feature details, and how Filters integrates with Data Grid and other ReUI primitives.
What is Shadcn Filters?
ReUI Filters is a custom shadcn component that does not exist in the base shadcn/ui library. It generates a filter panel from a schema of field definitions: each field maps to a column in a TanStack Table instance or a standalone filter state. Field types include text search, single and multi-select dropdowns, calendar date ranges via react-day-picker, number ranges, and boolean toggles. Zod validates filter values before they reach the table or API.
Filter state can be controlled locally or serialized to URL search parameters using nuqs: the typed URL state library built for Next.js App Router. This means users can share filtered views, the browser back button restores filter state, and analytics tools capture filter combinations as URL parameters.
Why Use Shadcn Filters?
Every data-heavy interface needs filters: analytics dashboards, CRM contact lists, order management tables, log viewers, and product catalogs all benefit from a consistent, type-safe filter panel. Building filters ad-hoc per page leads to duplicated logic, inconsistent UX, and URL state management debt. ReUI Filters centralizes all of that in a composable schema-driven component.
The async mode component fires a debounced callback on filter change instead of updating a local table instance: enabling server-side filtering for large datasets where full client-side data is impractical. Pair with Shadcn Data Grid for the most complete data management interface in ReUI.
Libraries and ReUI Filters Primitives
ReUI Filters integrates @tanstack/react-table for column filter state, nuqs for URL search param serialization, Zod for filter value validation, date-fns for date formatting and localization, and react-day-picker for calendar date range inputs.
The filter panel composes shadcn Dropdown Menu, Popover, Calendar, Badge, Button, and ScrollArea. Badge renders applied filter chips; Popover contains the date range calendar; ScrollArea handles long option lists in multi-select fields.
Shadcn Filters Features
- TanStack Table Column Filter API. Filters map directly to TanStack Table column definitions. Set column.getFilterValue() and column.setFilterValue() for client-side filtering, or use manualFiltering with an async callback for server-side filtering.
- nuqs URL State Persistence. Active filter state serializes to URL search parameters via nuqs. Users can share filtered views, the browser back button restores filters, and Next.js App Router handles hydration without extra code.
- Zod Filter Validation. Filter values pass through a Zod schema before reaching the table or API call. Invalid inputs are rejected before triggering a filter update, preventing malformed API requests.
- Date Range Filters. Date range fields use react-day-picker inside a Popover for accessible calendar-based date selection. Integrates with date-fns for locale-aware formatting and range validation.
- Multi-Field Type Support. Text search, single select, multi-select with checkboxes, date ranges, number ranges, and boolean toggles, all defined in a single field schema and rendered by the filter panel automatically.
- Applied Filter Chips. Active filters render as shadcn Badge chips with remove actions. A clear-all button resets all filters and, if nuqs is active, clears the URL state.
- Async and Server-Side Filter Mode. The async filter component debounces filter changes and fires a callback instead of updating local table state. Wire to SWR, React Query, or Next.js Server Actions for large datasets where client-side filtering is not feasible.
- i18n Support. Field labels, placeholder text, and date formatting accept locale props. The i18n filter component shows English and localized variants side by side using date-fns locale utilities.
- Size Variants and Custom Controls. Compact (small), default, and large size variants adapt to dense admin toolbars or spacious marketing dashboards. Custom control rendering allows any shadcn input component inside a filter field.
ReUI Filters: In-House Custom Shadcn Component
ReUI Filters is an in-house component built and maintained by the ReUI team as part of the ReUI open-source library. It is designed to integrate seamlessly into any shadcn/ui project: following the same copy-and-own installation model. The component source lands directly in your repository; you own it, extend it, and style it with your Tailwind CSS tokens. ReUI Filters is a custom schema-driven filter panel not available in base shadcn/ui. It integrates directly with @tanstack/react-table column filter APIs, persists filter state to URL search params via nuqs, validates inputs with zod, and supports async server-side filtering for large datasets. The i18n and custom control components extend it for global products.
The component is available in two API flavors to match your primitive stack: a Radix UI version for teams using Radix-based shadcn primitives, and a Base UI version for teams on @base-ui/react. Both versions share identical visual output and Tailwind CSS styling: only the underlying headless primitive differs. ReUI maintains 22 such in-house components, all available in both Radix and Base UI versions, each with dedicated documentation covering the full component API, usage examples, and prop references.
Integrating With Other Components
Filters is designed to pair with Shadcn Data Grid. Use Filters above the grid for a full data management interface with column filtering, sort, pagination, and CRUD: the data grid with filters components show this complete composition.
Use Shadcn Badge for applied filter chips, Shadcn Calendar inside Shadcn Popover for date range fields, and Shadcn Select or Shadcn Combobox for option-based fields that need search.
Wrap filter panels in Shadcn Sheet for a slide-out mobile filter drawer, or Shadcn Collapsible for an inline expandable filter section above a table. Use Shadcn Button for the custom trigger component.
Data Grid Blocks in ReUI Pro
The free data grid examples above cover focused, single purpose patterns. ReUI Pro extends them with 47 production ready data grid blocks, complete sections that compose the same primitives into full screens. Browse them by category:
- Base (8 blocks)Complete table screens with toolbar filters and pagination for CRM, support, team, project, and pricing data.
- Advanced (8 blocks)Analytics grids with in-cell charts, KPI rollups, a tree view and an SLO chart, plus a review queue, a stock mix sheet, a pro forma and a visit planner.
- Columns (5 blocks)Column visibility, pinning, resizing, density, and settings controls.
- Drag & Drop (4 blocks)Drag-and-drop row and column reordering with sortable handles.
- Editing (6 blocks)Inline create, edit, and delete cells for full CRUD workflows.
- Expansion (3 blocks)Expandable parent rows with nested sub-rows and master-detail panels.
- Filtering (4 blocks)Search, faceted filters, filter builders, and status tab toolbars.
- Grouping (7 blocks)Rows grouped into banded sections with stage and category headers.
- Virtualization (2 blocks)Virtualized rendering for large datasets with smooth scrolling.
Frequently Asked Questions
How do filters connect to TanStack Table?
How does URL filter state work with nuqs?
Can filters work with server-side data?
How are date range filters implemented?
Can I add custom filter controls beyond the built-in types?
Does the filter panel support i18n?
Start building with ReUI Pro today.
Every Pro block, every style, and every future addition, with one license for unlimited projects.
From $249, once. Lifetime updates.