Data Table Filter

A composable filter bar for data tables with text, number, date, option, and multi-option column types.

Client Only

Installation

pnpm dlx @docyrus/cli add @docyrus/ui-data-table-filter

UI Primitives(9 components)

npx shadcn@latest add button calendar checkbox command input popover separator slider tabs

Usage

import {
  DataTableFilter,
  useDataTableFilters
} from '@docyrus/ui/components/data-table-filter';

const columnsConfig = [
  {
    id: 'title',
    displayName: 'Title',
    icon: TextIcon,
    type: 'text' as const,
    accessor: (row: Task) => row.title
  },
  {
    id: 'status',
    displayName: 'Status',
    icon: CircleIcon,
    type: 'option' as const,
    accessor: (row: Task) => row.status,
    options: [
      { label: 'Todo', value: 'todo' },
      { label: 'Done', value: 'done' }
    ]
  },
  {
    id: 'effort',
    displayName: 'Effort',
    icon: HashIcon,
    type: 'number' as const,
    accessor: (row: Task) => row.effort,
    min: 0,
    max: 100
  },
  {
    id: 'createdAt',
    displayName: 'Created',
    icon: CalendarIcon,
    type: 'date' as const,
    accessor: (row: Task) => row.createdAt
  }
] as const;

function MyFilters() {
  const { columns, filters, actions, strategy } = useDataTableFilters({
    strategy: 'client',
    data: myData,
    columnsConfig
  });

  return (
    <DataTableFilter
      columns={columns}
      filters={filters}
      actions={actions}
      strategy={strategy}
      locale="en" />
  );
}

Features

5 column data types — text, number, date, option, multiOption
Client & server strategies — Client-side filtering with automatic option counting, or server-side with external filter state
Rich operators — Type-specific operators (contains, is between, is any of, etc.)
i18n support — Built-in locales: English, French, Dutch, German, Chinese (Simplified & Traditional)
Faceted counts — Option counts with visual indicators
Keyboard friendly — Full keyboard navigation through filter controls
Mobile responsive — Adapts layout for mobile viewports
Controlled & uncontrolled — Use internal state or manage filters externally

API Reference

useDataTableFilters

The main hook that creates columns, manages filter state, and returns action handlers.

Prop	Type	Default	Description
`strategy`	`'client' \| 'server'`	—	Filter strategy
`data`	`Array<TData>`	—	Row data array
`columnsConfig`	`ReadonlyArray<ColumnConfig<TData>>`	—	Column configuration array
`defaultFilters`	`FiltersState`	—	Initial filter values (uncontrolled)
`filters`	`FiltersState`	—	External filter state (controlled)
`onFiltersChange`	`Dispatch<SetStateAction<FiltersState>>`	—	Filter state setter (controlled)
`options`	`Partial<Record<OptionColumnIds, ColumnOption[]>>`	—	Server-provided options for option columns
`faceted`	`Partial<Record<...>>`	—	Server-provided faceted counts and min/max values

Returns:

Field	Type	Description
`columns`	`Array<Column<TData>>`	Enriched column objects with properties
`filters`	`FiltersState`	Current filter state
`actions`	`DataTableFilterActions`	Filter action handlers
`strategy`	`FilterStrategy`	Active strategy

DataTableFilter

The rendered filter bar component.

Prop	Type	Default	Description
`columns`	`Array<Column<TData>>`	—	Columns from `useDataTableFilters`
`filters`	`FiltersState`	—	Filter state from `useDataTableFilters`
`actions`	`DataTableFilterActions`	—	Actions from `useDataTableFilters`
`strategy`	`FilterStrategy`	—	Strategy from `useDataTableFilters`
`locale`	`Locale`	`'en'`	Display locale

Type Reference

ColumnConfig

Configuration for a single filterable column.

Field	Type	Required	Description
`id`	`string`	Yes	Unique column identifier
`accessor`	`(row: TData) => TVal`	Yes	Function to extract value from row data
`displayName`	`string`	Yes	Display label for the filter UI
`icon`	`LucideIcon`	Yes	Icon component shown next to the label
`type`	`ColumnDataType`	Yes	Column data type
`options`	`Array<ColumnOption>`	For option/multiOption	Available options for selection
`facetedOptions`	`Map<string, number>`	No	Pre-computed faceted option counts
`min`	`number`	For number	Minimum value constraint
`max`	`number`	For number	Maximum value constraint
`transformOptionFn`	`(value) => ColumnOption`	No	Transform raw values to options
`orderFn`	`(a, b) => number`	No	Custom sort order for options

ColumnDataType

type ColumnDataType = 'text' | 'number' | 'date' | 'option' | 'multiOption';

Type	Native Value	Description
`text`	`string`	Searchable text column
`number`	`number`	Numeric column with range support
`date`	`Date`	Date column with range support
`option`	`string`	Single-value from a list of options
`multiOption`	`Array<string>`	Zero or more values from a list of options

ColumnOption

Option item for option and multiOption columns.

Field	Type	Required	Description
`label`	`string`	Yes	Display label
`value`	`string`	Yes	Internal value
`icon`	`ReactElement \| ElementType`	No	Icon component or element

FilterStrategy

type FilterStrategy = 'client' | 'server';

client — Hook computes options, faceted counts, and min/max from the provided data array automatically.
server — You provide options and faceted counts externally. The hook only manages filter state.

FilterModel

Represents a single active filter.

Field	Type	Description
`columnId`	`string`	Column being filtered
`type`	`ColumnDataType`	Column data type
`operator`	`FilterOperators[type]`	Active operator
`values`	`FilterValues<type>`	Filter values

FiltersState

type FiltersState = Array<FilterModel>;

DataTableFilterActions

Method	Signature	Description
`addFilterValue`	`(column, values) => void`	Add values to an option/multiOption filter
`removeFilterValue`	`(column, values) => void`	Remove values from an option/multiOption filter
`setFilterValue`	`(column, values) => void`	Set filter values (any type)
`setFilterOperator`	`(columnId, operator) => void`	Change filter operator
`removeFilter`	`(columnId) => void`	Remove a single filter
`removeAllFilters`	`() => void`	Clear all active filters

Locale

type Locale = 'en' | 'fr' | 'nl' | 'zh_CN' | 'zh_TW' | 'de';

Filter Operators

Text Operators

Operator	Description
`contains`	Value contains the search text
`does not contain`	Value does not contain the search text

Number Operators

Operator	Description
`is`	Equals the value
`is not`	Does not equal the value
`is less than`	Less than the value
`is less than or equal to`	Less than or equal
`is greater than`	Greater than the value
`is greater than or equal to`	Greater than or equal
`is between`	Between two values (inclusive)
`is not between`	Outside the range

Date Operators

Operator	Description
`is`	Exact date match
`is not`	Not this date
`is before`	Before the date
`is on or before`	On or before the date
`is after`	After the date
`is on or after`	On or after the date
`is between`	Between two dates
`is not between`	Outside the date range

Option Operators

Operator	Description
`is`	Matches the selected option
`is not`	Does not match
`is any of`	Matches any of the selected options
`is none of`	Matches none of the selected options

Multi-Option Operators

Operator	Description
`include`	Includes the selected value
`exclude`	Excludes the selected value
`include any of`	Includes any of the selected values
`include all of`	Includes all selected values
`exclude if any of`	Excludes if any of the values match
`exclude if all`	Excludes if all values match

Data Table Filter

On this page