║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║

---

title: Data Table description: A powerful and flexible data table component for displaying, filtering, sorting, and paginating tabular data. preview: true links: doc: https://tanstack.com/table/latest/docs/introduction api: /docs/components/data-table#api-reference

<ComponentTabs name="data-table-demo" align="start" className="p-4" />

Installation

<Steps> <Step> Install the main component and dependencies:

```package-install
npx shadcn@2.4.0-canary.12 add "https://diceui.com/r/data-table"
```

</Step> <Step> Wrap your application with the [`NuqsAdapter`](https://nuqs.47ng.com/docs/adapters) for query state management:

```tsx
import { NuqsAdapter } from "nuqs/adapters/next/app";

<NuqsAdapter>
  <App />
</NuqsAdapter>
```

</Step> <Step> Install the [`DataTableSortList`](#datatablesortlist) (optional):

```package-install
npx shadcn@2.4.0-canary.12 add "https://diceui.com/r/data-table-sort-list"
```

</Step> <Step> Install the [`DataTableFilterList`](#datatablefilterlist) (optional):

```package-install
npx shadcn@2.4.0-canary.12 add "https://diceui.com/r/data-table-filter-list"
```

</Step> <Step> Install the [`DataTableFilterMenu`](#datatablefiltermenu) (optional):

```package-install
npx shadcn@2.4.0-canary.12 add "https://diceui.com/r/data-table-filter-menu"
```

</Step> <Step> Install the [`DataTableActionBar`](#datatableactionbar) (optional):

```package-install
npx shadcn@2.4.0-canary.12 add "https://diceui.com/r/data-table-action-bar"
```

</Step> </Steps>

Layout

Import the components and compose them together:

import { DataTable } from "@/components/data-table/data-table";
import { DataTableToolbar } from "@/components/data-table/data-table-toolbar";
import { DataTableAdvancedToolbar } from "@/components/data-table/data-table-advanced-toolbar";
import { DataTableFilterList } from "@/components/data-table/data-table-filter-list";
import { DataTableSortList } from "@/components/data-table/data-table-sort-list";
import { useDataTable } from "@/hooks/use-data-table";

const { table } = useDataTable({
  data,
  columns,
  pageCount,
});

// With standard toolbar
<DataTable table={table}>
  <DataTableToolbar table={table}>
    <DataTableSortList table={table} />
  </DataTableToolbar>
</DataTable>

// With advanced toolbar
<DataTable table={table}>
  <DataTableAdvancedToolbar table={table}>
    <DataTableFilterList table={table} />
    <DataTableSortList table={table} />
  </DataTableAdvancedToolbar>
</DataTable>

Walkthrough

<Steps> <Step> Define columns with appropriate metadata:

```tsx
import { Text, CalendarIcon, DollarSign } from "lucide-react";
import { DataTableColumnHeader } from "@/components/data-table/data-table-column-header";

const columns = React.useMemo(() => [
  {
    // Provide an unique id for the column
    // This id will be used as query key for the column filter
    id: "title", // [!code highlight]
    accessorKey: "title",
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Title" />
    ),
    cell: ({ row }) => <div>{row.getValue("title")}</div>,
    // Define the column meta options for sorting, filtering, and view options
    meta: { // [!code highlight]
      label: "Title", // [!code highlight]
      placeholder: "Search titles...", // [!code highlight]
      variant: "text", // [!code highlight]
      icon: Text, // [!code highlight]
    }, // [!code highlight] 
    // By default, the column will not be filtered. Set to `true` to enable filtering.
    enableColumnFilter: true, // [!code highlight]
  },
], []);
```

</Step> <Step> Initialize the table state using the `useDataTable` hook:

```tsx
import { useDataTable } from "@/hooks/use-data-table";

function DataTableDemo() {
  const { table } = useDataTable({
    data,
    columns,
    // Pass the total number of pages for the table
    pageCount, // [!code highlight]
    initialState: {
      sorting: [{ id: "createdAt", desc: true }],
      pagination: { pageSize: 10 },
    },
    // Unique identifier for rows, can be used for unique row selection
    getRowId: (row) => row.id, // [!code highlight]
  });

  return (
    // ... render table
  );
}
```

</Step> <Step> Pass the table instance to the `DataTable`, and `DataTableToolbar` components:

```tsx
import { DataTable } from "@/components/data-table/data-table";
import { DataTableToolbar } from "@/components/data-table/data-table-toolbar";
import { DataTableSortList } from "@/components/data-table/data-table-sort-list";

function DataTableDemo() {
  return (
    <DataTable table={table}>
      <DataTableToolbar table={table}>
        <DataTableSortList table={table} />
      </DataTableToolbar>
    </DataTable>
  );
}
```

</Step> <Step> For advanced filtering, use the `DataTableAdvancedToolbar` component:

```tsx
import { DataTableAdvancedToolbar } from "@/components/data-table/data-table-advanced-toolbar";
import { DataTableFilterList } from "@/components/data-table/data-table-filter-list";
import { DataTableFilterMenu } from "@/components/data-table/data-table-filter-menu";

function DataTableDemo() {
  return (
    <DataTable table={table}>
      <DataTableAdvancedToolbar table={table}>
        <DataTableFilterList table={table} />
        <DataTableSortList table={table} />
      </DataTableAdvancedToolbar>
    </DataTable>
  );
}
```

</Step> <Step> Alternatively, swap out `DataTableFilterList` with `DataTableFilterMenu` for a command palette-style interface:

```tsx
import { DataTableAdvancedToolbar } from "@/components/data-table/data-table-advanced-toolbar";
import { DataTableFilterList } from "@/components/data-table/data-table-filter-list"; // [!code --]
import { DataTableFilterMenu } from "@/components/data-table/data-table-filter-menu"; // [!code ++]
import { DataTableSortList } from "@/components/data-table/data-table-sort-list";

function DataTableDemo() {
  return (
    <DataTable table={table}>
      <DataTableAdvancedToolbar table={table}>
        {/* [!code --] */}
        <DataTableFilterList table={table} />
        {/* [!code ++] */}
        <DataTableFilterMenu table={table} />
        <DataTableSortList table={table} />
      </DataTableAdvancedToolbar>
    </DataTable>
  );
}
```

</Step> <Step> Render an action bar on row selection:

```tsx
import { DataTableActionBar } from "@/components/data-table/data-table-action-bar";
import { CustomTableActions } from "@/components/data-table/custom-table-actions";

function DataTableDemo() {
  return (
    <DataTable 
      table={table}
      actionBar={
        <DataTableActionBar table={table}>
          {/* Add your custom actions here */}
          <CustomTableActions />
        </DataTableActionBar>
      }
    >
      <DataTableToolbar table={table} />
    </DataTable>
  );
}
```

</Step> </Steps>

API Reference

Column Definitions

The column definitions are used to define the columns of the data table.

const columns = React.useMemo<ColumnDef<Project>[]>(() => [
  {
    // Required: Unique identifier for the column
    id: "title", // [!code highlight]
    // Required: Key to access the data, `accessorFn` can also be used
    accessorKey: "title", // [!code highlight]
    // Optional: Custom header component
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Title" />
    ),
    // Optional: Custom cell component
    cell: ({ row }) => <div>{row.getValue("title")}</div>,
    // Optional: Meta options for filtering, sorting, and view options
    meta: {
      label: "Title",
      placeholder: "Search titles...",
      variant: "text",
      icon: Text,
    },
    // By default, the column will not be filtered. Set to `true` to enable filtering.
    enableColumnFilter: true, // [!code highlight]
  },
  {
    id: "status",
    // Access nested data using `accessorFn`
    accessorFn: (row) => row.lineItem.status,
    header: "Status",
    meta: {
      label: "Status",
      variant: "select",
      options: [
        { label: "Active", value: "active" },
        { label: "Inactive", value: "inactive" },
      ],
    },
    enableColumnFilter: true,
  },
], []);

Properties

Core configuration options for defining columns.

<PropsTable data={[ { title: "id", description: "Required: Unique identifier for the column", }, { title: "accessorKey", description: "Required: Key to access the data from the row", }, { title: "accessorFn", description: "Optional: Custom accessor function to access data", }, { title: "header", description: "Optional: Custom header component with column props", }, { title: "cell", description: "Optional: Custom cell component with row props", }, { title: "meta", description: "Optional: Meta options for accessing column metadata", }, { title: "enableColumnFilter", description: "By default, the column will not be filtered. Set to true to enable filtering", }, { title: "enableSorting", description: "Enable sorting for this column", }, { title: "enableHiding", description: "Enable column visibility toggle", }, ]} />

Column Meta

Column meta options for filtering, sorting, and view options.

<PropsTable data={[ { title: "label", description: "The display name for the column", }, { title: "placeholder", description: "The placeholder text for filter inputs", }, { title: "variant", description: "The type of filter to use (text, number, select, etc.)", }, { title: "options", description: "For select/multi-select filters, an array of options with label, value, and optional count and icon", }, { title: "range", description: "For range filters, a tuple of [min, max] values", }, { title: "unit", description: "For numeric filters, the unit to display (e.g., 'hr', '$')", }, { title: "icon", description: "The react component to use as an icon for the column", }, ]} />

Filter Variants

Available filter variants for column meta.

<PropsTable variant="title" data={[ { title: "text", description: "Text search with contains, equals, etc.", }, { title: "number", description: "Numeric filters with equals, greater than, less than, etc.", }, { title: "range", description: "Range filters with minimum and maximum values", }, { title: "date", description: "Date filters with equals, before, after, etc.", }, { title: "dateRange", description: "Date range filters with start and end dates", }, { title: "boolean", description: "Boolean filters with true/false values", }, { title: "select", description: "Single-select filters with predefined options", }, { title: "multiSelect", description: "Multi-select filters with predefined options", }, ]} />

Reference the TanStack Table Column Definitions Guide for detailed column definition guide.

useDataTable

A hook for initializing the data table with state management.

<AutoTypeTable path="./types/docs/data-table.ts" name="UseDataTableProps" />

DataTable

The main data table component.

<AutoTypeTable path="./types/docs/data-table.ts" name="DataTableProps" />

DataTableColumnHeader

Custom header component for columns with sorting.

<AutoTypeTable path="./types/docs/data-table.ts" name="DataTableColumnHeaderProps" />

DataTableToolbar

Standard toolbar with filtering and view options.

<AutoTypeTable path="./types/docs/data-table.ts" name="DataTableToolbarProps" />

DataTableAdvancedToolbar

Advanced toolbar with more comprehensive filtering capabilities.

<AutoTypeTable path="./types/docs/data-table.ts" name="DataTableAdvancedToolbarProps" />

DataTableViewOptions

Controls column visibility and display preferences in the data table.

<AutoTypeTable path="./types/docs/data-table.ts" name="DataTableViewOptionsProps" />

DataTableSortList

List of applied sorting with ability to add, remove, and modify sorting.

<AutoTypeTable path="./types/docs/data-table.ts" name="DataTableSortListProps" />

DataTableFilterList

List of applied filters with ability to add, remove, and modify filters.

<AutoTypeTable path="./types/docs/data-table.ts" name="DataTableFilterListProps" />

DataTableFilterMenu

Filter menu with ability to add, remove, and modify filters.

<AutoTypeTable path="./types/docs/data-table.ts" name="DataTableFilterMenuProps" />

DataTableActionBar

Floating action bar component for actions for selected rows.

<AutoTypeTable path="./types/docs/data-table.ts" name="DataTableActionBarProps" />

DataTablePagination

Pagination controls for the data table.

<AutoTypeTable path="./types/docs/data-table.ts" name="DataTablePaginationProps" />

Accessibility

Keyboard Interactions

<KeyboardShortcutsTable shortcuts={[ { keys: ["Ctrl + Shift + F", "Cmd + Shift + F"], description: "Toggles the filter menu.", }, { keys: ["Ctrl + Shift + S", "Cmd + Shift + S"], description: "Toggles the sort menu.", }, { keys: ["Backspace", "Delete"], description: "Removes the focused filter/sort item. Removes the last applied filter/sort when menu trigger is focused.", }, ]} />

Credits

• shadcn/ui - For the initial implementation of the data table.

║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║