# Data Table Filter
URL: /docs/web/components/data-table-filter

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

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

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

import { PropControls } from '@/components/prop-controls';
import { useDemoData } from '@/data/data-table-filter-data';

export function DataTableFilterDemo() {
  const {
    data, columnsConfig, props: extraProps, controls
  } = useDemoData();
  const [open, setOpen] = useState(false);

  const {
    columns, filters, actions, strategy
  } = useDataTableFilters({
    strategy: extraProps.strategy,
    data,
    columnsConfig
  });

  return (
    <div className="w-full">
      <div className="mb-3 flex justify-end">
        <button
          type="button"
          className="inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-sm font-medium transition-colors hover:bg-accent"
          onClick={() => setOpen(prev => !prev)}>
          <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z" /><circle cx="12" cy="12" r="3" /></svg>
          Configure
          <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className={cn('transition-transform duration-200', open && 'rotate-180')}><path d="m6 9 6 6 6-6" /></svg>
        </button>
      </div>
      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="mb-4 rounded-lg border border-border bg-muted/30 p-4 grid gap-6">
            <div className="flex flex-wrap items-center gap-4">
              
            </div>
          </div>
        </div>
      </div>
      
    </div>
  );
}
```

## Installation

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

## Usage

```tsx
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 (
    
  );
}
```

## 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

```tsx
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

```tsx
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

```tsx
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

```tsx
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 |