Introduction

This is an add-on to your existing shadcn/ui data table component. It adds client-side filtering with a clean, modern UI inspired by Linear.

This component relies on TanStack Table, a headless UI for building powerful tables & datagrids.

Prerequisites

Before you begin:

• Create your <DataTable /> component. You can follow the shadcn/ui docs for guidance.
• Ensure you're using client-side filtering.

Installation

From the command line, install the component into your project:

pnpm dlx shadcn@latest add https://ui.bazza.dev/r/data-table-filter.json

Concepts

Let's take a look at the most important concepts for using this component.

Column data types

Whenever you want to filter a column, you need to define what type of data it contains. ColumnDataType identifies the types of data we currently support filtering for.

Set the type property of the column meta (explained below) to one of the following values:

export type ColumnDataType =
  | 'text'         /* Text data */
  | 'number'       /* Numerical data */
  | 'date'         /* Dates */
  | 'option'       /* Single-valued option (e.g. status) */
  | 'multiOption'  /* Multi-valued option (e.g. labels) */

Column options

For option and multiOption columns, we represent each possible option as a ColumnOption:

export interface ColumnOption {
  /* The label to display for the option. */
  label: string
  /* The internal value of the option. */
  value: string
  /* An optional icon to display next to the label. */
  icon?: React.ReactElement | React.ElementType
}

label

This is the label or display name for the option.

value

This is the interval value for the option and must be unique across all options for a given column.

For an option column, the filter value is a string which matches the value property of chosen column option.

For a multiOption column, the filter value is a string[] where each array member is the value property of the chosen column option.

icon

Optionally, you can provide an icon to represent the column option.

An icon must be provided for every column option. Otherwise, icons will not be displayed for the column's options.

Column meta

The star of the show is the ColumnMeta interface, which defines the metadata shape for a column.

The metadata for each column is configured using the column's meta property, which accepts an object of type ColumnMeta.

export type ElementType<T> = T extends (infer U)[] ? U : T
 
interface ColumnMeta<TData extends RowData, TValue> {
  /* The display name of the column. */
  displayName: string
  /* The column icon. */
  icon: LucideIcon
  /* The data type of the column. */
  type: ColumnDataType
  /* An optional list of options for the column. */
  /* This is used for columns with type 'option' or 'multiOption'. */
  /* If the options are known ahead of time, they can be defined here. */
  /* Otherwise, they will be dynamically generated based on the data. */
  options?: ColumnOption[]
  /* An optional function to transform columns with type 'option' or 'multiOption'. */
  /* This is used to convert each raw option into a ColumnOption. */
  transformOptionFn?: (
    value: ElementType<NonNullable<TValue>>,
  ) => ColumnOption
  /* An optional "soft" max for the range slider. */
  /* This is used for columns with type 'number'. */
  max?: number
}

Let's go through each property in detail:

displayName

This is the display name for the column. It is used when showing the property in various filter-related interfaces, such as the filter menu.

icon

This is the icon for the column. It is displayed alongside the displayName.

type

This is the data type of the column. It is used to determine many core functionalities of the data table filter component, such as:

• Rendering the correct user interfaces for modifying the filter values.
• Determining the correct filter operators for the property.

options

If you have a static list of options for the column, you can pass them as an ColumnOption[] object.

transformOptionFn

This is used when you're inferring the available options for a column using the column data itself.

The transformOptionFn will be used to transform each unique column value into a ColumnOption object.

Internally, this is used when determining the available options for a column when the options property is not defined.

/* Get all non-null column values */
const columnVals = table
  .getCoreRowModel()
  .rows.flatMap((r) => r.getValue<TValue>(id))
  .filter((v): v is NonNullable<TValue> => v !== undefined && v !== null)
 
/* Keep unique values */
/* Transform column values into `ColumnOption` objects */
const options = uniq(columnVals).map(meta.transformOptionFn)

max

Sets a "soft" maximum value for the range slider when filtering on a number column.

If omitted, the range slider will compute the maximum value based on the available column data.

Usage

Add component

Import the <DataTableFilter /> component and pass it your table instance:

import { DataTableFilter } from '@/components/data-table-filter'
 
export default function DataTable() {
  return (
    <div>
      <DataTableFilter table={table} />
      <div className="rounded-md border">
        <Table>
          {/* ... */}
        </Table>
      </div>
    </div>
  )
}

Update columns

Updating your columns

For each column that you want to be filterable, you need to do two things:

• Use our provided filterFn() for filtering the column data.
• Add the meta property using the defineMeta() helper function.

For the filter function, we provide one for you - it is conveniently called filterFn() and takes a single argument type which is the column data type (i.e. ColumnDataType).

For the column meta, we provide a helper function called defineMeta() which takes two arguments: (1) the property name from your data object, and (2) an object containing the column meta.

When specifying the property name, you must use an accessor function, as demonstrated below.

export const columns = [
  columnHelper.accessor('status', {
    filterFn: filterFn('option'),
    meta: defineMeta(row => row.status, {
      displayName: 'Status',
      type: 'option',
      icon: CircleDotDashedIcon,
      options: ISSUE_STATUSES,
    }),
  }),
]

Integrations

nuqs

You can use nuqs to persist the filter state in the URL.

1. Install the nuqs and zod packages:

pnpm add nuqs zod

2. Use the appropriate nuqs adapter for your framework from the nuqs docs.

3. Create your Zod schema for the query filter state:

import { z } from 'zod'
 
const dataTableFilterQuerySchema = z
  .object({
    id: z.string(),
    value: z.object({
      operator: z.string(),
      values: z.any(),
    }),
  })
  .array()
  .min(0)
 
type DataTableFilterQuerySchema = z.infer<typeof dataTableFilterQuerySchema>

4. Create the following helper function:

function initializeFiltersFromQuery<TData, TValue>(
  filters: DataTableFilterQuerySchema,
  columns: ColumnDef<TData, TValue>[],
) {
  return filters && filters.length > 0
    ? filters.map((f) => {
        const columnMeta = columns.find((c) => c.id === f.id)!.meta!
 
        const values =
          columnMeta.type === 'date'
            ? f.value.values.map((v: string) => new Date(v))
            : f.value.values
 
        return {
          ...f,
          value: {
            operator: f.value.operator,
            values,
            columnMeta,
          },
        }
      })
    : []
}

5. Update your date table component file:

import { parseAsJson, useQueryState } from 'nuqs'
import { type ColumnDef } from '@tanstack/react-table'
 
export default function YourDataTableComponent() {
  const [queryFilters, setQueryFilters] = useQueryState(
    'filter',
    parseAsJson(dataTableFilterQuerySchema.parse).withDefault([]),
  )
  const [columnFilters, setColumnFilters] = React.useState<ColumnFiltersState>(
    // Replace `Issue` with your data type
    () => initializeFiltersFromQuery(queryFilters, columns as ColumnDef<Issue>[]),
  )
 
  const table = useReactTable({
    /* ... */
  })
 
  React.useEffect(() => {
    setQueryFilters(
      columnFilters.map((f) => ({
        id: f.id,
        value: { ...(f.value as any), columnMeta: undefined },
      })),
    )
  }, [columnFilters, setQueryFilters])
 
  /* ... */
}

Overview

Let's take a high-level look at how we've created the data table filter component.

This will help you understand what each file contains and the general component composition.

File structure

The data table filter component is composed of several files.

Components are placed in the @/components directory - all components are placed in a single file for ease of distribution:

• data-table-filter.tsx: The main component file.

Types, interfaces, and utilities are placed in the @/lib directory:

• array.ts: Utility functions for working with arrays.
• filters.ts: All TypeScript types, interfaces, and constants related to the data table filter component. Also includes the filter functions filterFn() for each column type.
• table.ts: Utility functions for working with the TanStack Table library.

Component structure

A PropertyFilterItem component is composed of the following parts:

• PropertyFilterSubject shows the name and (optionally) icon of the property being filtered on.
• PropertyFilterOperator shows the operator used to filter on the property.
• PropertyFilterValue shows the actual filter value.

The composition of a property filter item.

The PropertyFilterOperator and PropertyFilterValue components are represented by a Controller which is essentially a Popover with an associated trigger and content.

We can break down the PropertyFilterValueController as an example:

• PropertyFilterValueDisplay is the popover trigger. This displays the filter value for the associated property.
• PropertyFilterValueMenu is the popover content. This renders the menu for modifying the filter value.

The composition of a property filter value controller.

The PropertyFilterOperatorController has a similar composition and can be inferred from the above description and image.

Changelog

2025.04.01

This adds support for filtering columns where the column value is not strictly a property of the original data. This was not possible before, due to the limitation of defineMeta's first argument, which only accepted a direct property on the initial data type.

You can now filter columns where the value is:

• a deeply nested property (i.e. user.name)
• accessed using a function (i.e. row => row.user.name.split(' ')[0])

To accomplish this, we've decided to change the interface for the defineMeta helper function. The first property is now an accessor function, instead of an accessor key.

See the example below for how to migrate:

type Issue = {
  status: string
  user: {
    name: string
  }
}

const columns = [
  /* ... */
  columnHelper.accessor('status', {
    meta: defineMeta(
      'status', 
      row => row.status, 
      { 
        type: 'option',
        icon: CircleDotDashedIcon,
        options: ISSUE_STATUSES,
      }
    ),
  }),
  columnHelper.accessor(row => row.user.name, {
    meta: defineMeta(
      row => row.user.name,
      { 
        type: 'option',
        icon: AvatarIcon,
        /* ... */
      }
    ),
  }),
]