DynamicFilterBar
A powerful, flexible filter bar with search, multi-operator support, sorting, URL sync, and optional async option fetching. Supports controlled/uncontrolled modes with custom renderers.
Installation
CLI
Dependencies
This component requires the following npm packages:
Registry Dependencies
This component also requires: https://ui.shadcn.com/r/styles/base-vega/button.json, https://ui.shadcn.com/r/styles/base-vega/utils.json
Usage
DynamicFilterBar is a powerful, flexible component for filtering and searching data. It supports static and dynamic filter options, multiple operators, sorting, URL synchronization, and optional async option fetching.
Keyboard navigation is fully supported: use Arrow Keys to navigate, Enter to select, Backspace to go back, and Escape to close.
Examples
With Sorting
Add sorters to enable result sorting with ascending/descending toggle. Try sorting by price and rating.
Zod Validation
Use Zod schemas to validate selected filter values. Try selecting prices and see validation feedback.
Custom Renderers
Customize how options and badges render with renderOption and renderBadge. Color-coded priority levels.
Async Option Fetching
Use fetchOptions for async data fetching with automatic debouncing and request cancellation. Type to search users with 300ms debounce.
URL Synchronization
Enable syncToUrl to automatically persist filter state to URL parameters. See the URL update as you add filters.
Controlled Mode
Use controlled mode to manage filter state externally with value and onChange props.
Controlled State Management
Both onChange and onApply callbacks fire for maximum flexibility.
Filter Operators
The following operators are available for filters:
Exact match. Single value only. Result shows a single filter value.
Exclude exact match. Single value only. Returns items NOT matching the value.
Match any of multiple values. Multi-value. Item must match ANY selected value.
Exclude multiple values. Multi-value. Item must NOT match ANY selected value.
API Reference
DynamicFilterBar Props
| Prop | Type | Default | Description |
|---|---|---|---|
filters* | FilterDefinition<TContext>[] | - | Array of filter definitions with keys, labels, operators, and options. |
sorters | SorterDefinition[] | - | Optional array of sorter definitions for result sorting. |
defaultSort | SortState | - | Initial sort state { key, direction }. |
context | TContext | - | Context object passed to filter methods for dynamic options. |
onApply | (state: FilterBarState) => void | - | Callback when filters or search change. |
onSortChange | (sort: SortState | null) => void | - | Callback when sort changes. |
syncToUrl | boolean | true | Automatically sync filter state to URL parameters. |
placeholder | string | "Filter or search..." | Input placeholder text. |
debounceMs | number | 300 | Debounce delay for async option fetching in milliseconds. |
preserveUrlParams | boolean | true | Preserve non-filter URL parameters when syncing. |
renderOption | (props: OptionRenderProps) => ReactNode | - | Custom renderer for dropdown options. |
renderBadge | (props: BadgeRenderProps) => ReactNode | - | Custom renderer for filter badges. |
FilterDefinition Type
| Prop | Type | Default | Description |
|---|---|---|---|
key* | string | - | Unique identifier for the filter. |
label* | string | - | Display name for the filter. |
icon* | LucideIcon | - | Icon component from lucide-react. |
operators* | FilterOperator[] | - | Available operators (is, is_not, one_of, none_of). |
options | FilterOption[] | - | Static list of options { value, label }. |
getOptions | (query: string, ctx: TContext) => FilterOption[] | - | Function to dynamically compute options based on input. |
fetchOptions | (query: string, ctx: TContext, signal?: AbortSignal) => Promise<FilterOption[]> | - | Function to asynchronously fetch options (automatically debounced). |
getDisplayValue | (value: string | string[], ctx: TContext) => string | - | Custom function to display filter values in badges. |
schema | z.ZodType<string | string[]> | - | Zod schema for validating selected filter values. |
FilterOperator Type
| Prop | Type | Default | Description |
|---|---|---|---|
id* | string | - | "is" | "is_not" | "one_of" | "none_of" |
symbol* | string | - | Display symbol (=, !=, ||, !||). |
label* | string | - | Display label (is, is not, one of, none of). |
FilterBarState Type
Keyboard Navigation
| Key | Behavior |
|---|---|
| ↓ / ↑ | Navigate options |
| Enter | Select highlighted option / Confirm multi-value |
| Tab | Select option and advance |
| Backspace | Go back a stage / Remove last selection |
| Escape | Close dropdown and reset |