Data Table

The data table renders rows and columns with sorting, filtering, row selection, and pagination. Use it for dashboards, admin lists, and any tabular data that needs interaction. It is built on TanStack Table, so you define columns with ColumnDef and compose the table from parts.

Preview

Installation

npx shadcn@latest add @cubby-ui/data-table

Usage

import {
	type ColumnDef,
	DataTable,
	DataTableContent,
	DataTableHeader,
	DataTableBody,
} from "@/components/ui/cubby-ui/data-table"

<DataTable>
  <DataTableContent>
    <DataTableHeader />
    <DataTableBody />
  </DataTableContent>
</DataTable>

Composition

DataTable builds the TanStack Table instance from columns and data and shares it through context. Compose the parts you need inside it.

DataTable                       (columns + data)
├── DataTableToolbar
│   ├── DataTableSearch
│   ├── DataTableColumnToggle
│   └── DataTableToolbarSeparator
├── DataTableContent
│   ├── DataTableHeader
│   ├── DataTableBody
│   └── DataTableFooter
└── DataTablePagination

<DataTable columns={columns} data={data} enableSorting>
  <DataTableToolbar>
    <DataTableSearch />
    <DataTableColumnToggle />
  </DataTableToolbar>
  <DataTableContent>
    <DataTableHeader enableSorting />
    <DataTableBody emptyState="No results found." />
  </DataTableContent>
</DataTable>

Examples

Sorting

Set enableSorting on DataTable and pass it to DataTableHeader; columns with string headers get clickable sort controls.

Row Selection

Set enableRowSelection to add a checkbox column, and control state with rowSelection and onRowSelectionChange.

Toolbar

Compose DataTableToolbar with DataTableSearch and DataTableColumnToggle, and set enableFiltering on DataTable so search works.

Striped

Set striped on DataTableContent for alternating row backgrounds.

Column Definitions

Define columns using the ColumnDef type from TanStack Table. Each column can have:

• accessorKey - The key to access data from the row
• header - Header content (string or render function)
• cell - Cell content render function
• enableSorting - Whether the column is sortable (default: true when enableSorting prop is set)

When enableSorting is enabled, columns with string headers automatically render a sortable button with direction indicators. Use meta.align to control header alignment, or a render function for fully custom headers.

import { type ColumnDef } from "@/registry/default/data-table/data-table"
 
const columns: ColumnDef<YourDataType>[] = [
  {
    accessorKey: "name",
    header: "Name", // Auto-renders with sort UI when enableSorting is true
  },
  {
    accessorKey: "amount",
    header: "Amount",
    meta: { align: "right" as const }, // Right-align the header
    cell: ({ row }) => {
      const amount = parseFloat(row.getValue("amount"))
      return <div className="text-right">${amount.toFixed(2)}</div>
    },
  },
  {
    accessorKey: "status",
    header: "Status",
    enableSorting: false, // Disable sorting for this column
  },
]

API Reference

DataTable

Root component that creates the TanStack Table instance and provides context to children.

DataTable's outer wrapper uses the same solidSurface(3, 1) + bg-muted pattern as Card inset and Table, a flat outlined gray frame. The inner DataTableContent Table inside has its own bg-muted/inner-card visual (body cells bg-surface-3 dark:bg-surface-1), with its outer Table styling suppressed (bg-transparent shadow-none ring-0) so the elevation lives on the DataTable wrapper only. See the Surfaces docs.

DataTableToolbar

Container for toolbar controls. Renders above the table content with visual connection to the header.

DataTableSearch

Search input that filters across all columns using the global filter.

DataTableColumnToggle

Dropdown button that allows users to show/hide columns.

This component has no configurable props. It automatically reads column visibility state from the DataTable context.

DataTableContent

Wrapper for the table that applies styling props. Accepts all Table component props.

DataTableHeader

Renders the table header with optional sort controls.

DataTableBody

Renders the table body with support for empty state.

DataTablePagination

Pagination controls with previous/next buttons and selection count.

DataTableToolbarSeparator

Visual separator for toolbar items. No configurable props.