Data Display

Data Table

TanStack table with sorting, search & faceted filters, pagination, row selection with bulk actions, column visibility, density, and loading/empty/error states.

Import

tsx

import { DataTable } from "@cooud-ui/ui";

bash

npx cooud-ui add data-table

Examples

Basic

The smallest setup: pass `columns` + `data`. With no opt-in props it renders a plain, accessible table — no toolbar, pagination, or selection.

Status	Email
success	ken99@example.com	$316.00
success	abe45@example.com	$242.00
processing	monserrat44@example.com	$837.00
success	silas22@example.com	$874.00
failed	carmella@example.com	$721.00
pending	jason.lee@example.com	$459.00

tsx

type Payment = {
  id: string;
  status: "pending" | "processing" | "success" | "failed";
  email: string;
  amount: number;
};

const columns: ColumnDef<Payment>[] = [
  {
    accessorKey: "status",
    header: "Status",
    cell: ({ row }) => <span className="capitalize">{row.getValue("status")}</span>,
  },
  {
    accessorKey: "email",
    header: "Email",
    cell: ({ row }) => <span className="lowercase">{row.getValue("email")}</span>,
  },
  {
    accessorKey: "amount",
    header: ({ column }) => (
      <Button
        variant="ghost"
        size="sm"
        className="-ml-2"
        onClick={() => column.toggleSorting(column.getIsSorted() === "asc")}
      >
        Amount
        <ArrowUpDown aria-hidden="true" />
      </Button>
    ),
    cell: ({ row }) => {
      const amount = Number.parseFloat(String(row.getValue("amount")));
      const formatted = new Intl.NumberFormat("en-US", {
        style: "currency",
        currency: "USD",
      }).format(amount);
      return <span className="font-mono tabular-nums">{formatted}</span>;
    },
  },
];

const data: Payment[] = [
  { id: "m5gr84i9", amount: 316, status: "success", email: "ken99@example.com" },
  { id: "3u1reuv4", amount: 242, status: "success", email: "abe45@example.com" },
  { id: "derv1ws0", amount: 837, status: "processing", email: "monserrat44@example.com" },
  { id: "5kma53ae", amount: 874, status: "success", email: "silas22@example.com" },
  { id: "bhqecj4p", amount: 721, status: "failed", email: "carmella@example.com" },
  { id: "p0r9twq2", amount: 459, status: "pending", email: "jason.lee@example.com" },
];

<DataTable columns={columns} data={data} />

Sortable

Use the exported `DataTableColumnHeader` in a column header to get an accessible, three-state sort toggle (asc → desc → none) with the right icon and aria-label. Click any header to sort.


Ada Lovelace	ada@cooud.dev	Owner	active	5
Grace Hopper	grace@cooud.dev	Admin	active	3
Alan Turing	alan@cooud.dev	Member	active	1
Katherine Johnson	katherine@cooud.dev	Member	invited	1
Margaret Hamilton	margaret@cooud.dev	Admin	active	2
Dennis Ritchie	dennis@cooud.dev	Viewer	suspended	0

tsx

import { DataTable, DataTableColumnHeader } from "@cooud-ui/ui";

const columns: ColumnDef<Member>[] = [
  {
    accessorKey: "name",
    header: ({ column }) => <DataTableColumnHeader column={column} title="Name" />,
    cell: ({ row }) => <span className="font-medium text-fg">{row.getValue("name")}</span>,
  },
  {
    accessorKey: "role",
    header: ({ column }) => <DataTableColumnHeader column={column} title="Role" />,
    cell: ({ row }) => <Badge variant="outline">{row.getValue("role")}</Badge>,
  },
  {
    accessorKey: "seats",
    header: ({ column }) => <DataTableColumnHeader column={column} title="Seats" />,
    cell: ({ row }) => (
      <span className="font-mono tabular-nums text-fg-secondary">{row.getValue("seats")}</span>
    ),
  },
];

<DataTable columns={columns} data={members} />

Search & filter

Opt into the toolbar with `searchable` for a debounce-free global search, and `facetedFilters` for multi-select column filters with live facet counts. A Reset clears everything.


Ada Lovelace	ada@cooud.dev	Owner	active	5
Grace Hopper	grace@cooud.dev	Admin	active	3
Alan Turing	alan@cooud.dev	Member	active	1
Katherine Johnson	katherine@cooud.dev	Member	invited	1
Margaret Hamilton	margaret@cooud.dev	Admin	active	2
Dennis Ritchie	dennis@cooud.dev	Viewer	suspended	0
Barbara Liskov	barbara@cooud.dev	Member	active	1
Donald Knuth	donald@cooud.dev	Member	invited	1
Edsger Dijkstra	edsger@cooud.dev	Viewer	active	1
Linus Torvalds	linus@cooud.dev	Admin	active	4
Tim Berners-Lee	tim@cooud.dev	Member	suspended	0
Radia Perlman	radia@cooud.dev	Member	active	2

tsx

const statusOptions = [
  { label: "Active", value: "active", icon: Check },
  { label: "Invited", value: "invited", icon: CircleDashed },
  { label: "Suspended", value: "suspended", icon: CircleSlash },
];

const statusFilter: DataTableFacetedFilter = {
  columnId: "status",
  title: "Status",
  options: statusOptions,
};

<DataTable
  columns={columns}
  data={members}
  searchable
  searchPlaceholder="Search members…"
  facetedFilters={[statusFilter]}
/>

Pagination

Set `pagination` to render the footer with a rows-per-page select, a row-range readout, and first/prev/next/last controls. Defaults are uncontrolled; pass `initialPageSize` and `pageSizeOptions` to tune.


Ada Lovelace	ada@cooud.dev	Owner	active	5
Grace Hopper	grace@cooud.dev	Admin	active	3
Alan Turing	alan@cooud.dev	Member	active	1
Katherine Johnson	katherine@cooud.dev	Member	invited	1
Margaret Hamilton	margaret@cooud.dev	Admin	active	2

1–5 of 12

Rows per page

Page 1 of 3

tsx

<DataTable
  columns={columns}
  data={members}
  pagination
  initialPageSize={5}
  pageSizeOptions={[5, 10, 20]}
/>

Selection & bulk actions

`enableRowSelection` prepends an accessible select-all/row checkbox column. Render contextual actions with `bulkActions` — a bar that appears only while rows are selected and receives the selected rows.


Ada Lovelace	ada@cooud.dev	Owner	active	5
Grace Hopper	grace@cooud.dev	Admin	active	3
Alan Turing	alan@cooud.dev	Member	active	1
Katherine Johnson	katherine@cooud.dev	Member	invited	1
Margaret Hamilton	margaret@cooud.dev	Admin	active	2

0 of 12 row(s) selected.

1–5 of 12

Rows per page

Page 1 of 3

tsx

<DataTable
  columns={columns}
  data={members}
  enableRowSelection
  pagination
  initialPageSize={5}
  bulkActions={(rows) => (
    <>
      <Button variant="outline" size="sm">
        <Mail aria-hidden="true" />
        Email {rows.length}
      </Button>
      <Button variant="destructive" size="sm">
        Remove
      </Button>
    </>
  )}
/>

Column visibility

`enableColumnVisibility` adds a “View” menu that toggles each hideable column on or off, so users can tailor the table to what they care about.


Ada Lovelace	ada@cooud.dev	Owner	active	5
Grace Hopper	grace@cooud.dev	Admin	active	3
Alan Turing	alan@cooud.dev	Member	active	1
Katherine Johnson	katherine@cooud.dev	Member	invited	1
Margaret Hamilton	margaret@cooud.dev	Admin	active	2
Dennis Ritchie	dennis@cooud.dev	Viewer	suspended	0

tsx

<DataTable
  columns={columns}
  data={members}
  searchable
  enableColumnVisibility
/>

Density

`enableDensityToggle` exposes a comfortable/compact switch in the toolbar; the `aria-pressed` button trims cell padding for data-dense views without touching your columns.


Ada Lovelace	ada@cooud.dev	Owner	active	5
Grace Hopper	grace@cooud.dev	Admin	active	3
Alan Turing	alan@cooud.dev	Member	active	1
Katherine Johnson	katherine@cooud.dev	Member	invited	1
Margaret Hamilton	margaret@cooud.dev	Admin	active	2
Dennis Ritchie	dennis@cooud.dev	Viewer	suspended	0

tsx

<DataTable
  columns={columns}
  data={members}
  searchable
  enableDensityToggle
/>

Loading

Pass `loading` to swap the body for shimmer rows that match your column count — no layout shift when the real data arrives. Toggle below to see the swap.

tsx

const [loading, setLoading] = useState(true);

<DataTable
  columns={columns}
  data={members}
  loading={loading}
  loadingRowCount={4}
/>

Empty

With no rows, the table renders a centered empty state. Override the copy — or drop in a full `Empty` composition — via the `emptyState` prop.


No members yet Invite teammates to see them listed here.

tsx

<DataTable
  columns={columns}
  data={[]}
  emptyState={
    <Empty>
      <EmptyIcon>
        <Inbox aria-hidden="true" />
      </EmptyIcon>
      <EmptyTitle>No members yet</EmptyTitle>
      <EmptyDescription>Invite teammates to see them listed here.</EmptyDescription>
    </Empty>
  }
/>

Error

Pass `error` to render an inline, `role="alert"` failure state. Provide `onRetry` to surface a Retry button — handy for refetching after a transient network error.


Couldn’t load team members. Check your connection and try again.

tsx

const [failed, setFailed] = useState(true);

<DataTable
  columns={columns}
  data={failed ? [] : members}
  error={failed ? "Couldn't load team members. Check your connection and try again." : undefined}
  onRetry={() => setFailed(false)}
/>

API Reference

Generated from the component's exported types.

DataTableProps

Prop	Type	Default	Description
`columns`*	`ColumnDef<TData, TValue>[]`	—	—
`data`*	`TData[]`	—	—
`searchable`	`boolean`	—	Show the toolbar with a global search field.
`searchPlaceholder`	`string`	—	Placeholder for the global search field. Defaults to "Search…".
`globalFilter`	`string`	—	Controlled global filter value. Implies a controlled toolbar search.
`onGlobalFilterChange`	`OnChangeFn<string>`	—	Called when the global filter changes (controlled or uncontrolled).
`facetedFilters`	`DataTableFacetedFilter[]`	—	Faceted (multi-select) column filters rendered in the toolbar.
`toolbarStart`	`ReactNode`	—	Extra nodes rendered on the left side of the toolbar.
`toolbarEnd`	`ReactNode`	—	Extra nodes rendered on the right side of the toolbar (before the View menu).
`enableColumnVisibility`	`boolean`	—	Show the "View" menu that toggles column visibility.
`columnVisibility`	`VisibilityState`	—	Controlled column visibility state.
`onColumnVisibilityChange`	`OnChangeFn<VisibilityState>`	—	Called when column visibility changes.
`sorting`	`SortingState`	—	Controlled sorting state.
`onSortingChange`	`OnChangeFn<SortingState>`	—	Called when sorting changes.
`manualSorting`	`boolean`	—	Server-side sorting: skip the client sort model.
`columnFilters`	`ColumnFiltersState`	—	Controlled column filters state.
`onColumnFiltersChange`	`OnChangeFn<ColumnFiltersState>`	—	Called when column filters change.
`manualFiltering`	`boolean`	—	Server-side filtering: skip the client filter model.
`pagination`	`boolean`	—	Show the pagination footer.
`paginationState`	`PaginationState`	—	Controlled pagination state.
`onPaginationChange`	`OnChangeFn<PaginationState>`	—	Called when pagination changes (controlled).
`manualPagination`	`boolean`	—	Server-side pagination: provide `pageCount` or `rowCount`.
`pageCount`	`number`	—	Total page count for server-side pagination.
`rowCount`	`number`	—	Total row count for server-side pagination (used to derive `pageCount`).
`initialPageSize`	`number`	—	Initial page size when uncontrolled. Defaults to 10.
`pageSizeOptions`	`number[]`	—	Page-size options offered in the footer select. Defaults to [10, 20, 30, 50].
`enableRowSelection`	`boolean \| ((row: Row<TData>) => boolean)`	—	Render a leading checkbox column with header select-all.
`rowSelection`	`RowSelectionState`	—	Controlled row-selection state.
`onRowSelectionChange`	`OnChangeFn<RowSelectionState>`	—	Called when row selection changes.
`bulkActions`	`(rows: Row<TData>[]) => ReactNode`	—	Render slot for bulk actions. Receives the currently selected rows; shown in a bar above the table only while at least one row is selected.
`density`	`DataTableDensity`	—	Controlled cell padding density. When provided, the toolbar toggle becomes controlled and you must update it via . Omit it to let the table manage density internally (see ).
`onDensityChange`	`(density: DataTableDensity) => void`	—	Called when the density toggle is pressed (controlled or uncontrolled).
`initialDensity`	`DataTableDensity`	—	Initial density when uncontrolled. Defaults to "comfortable".
`enableDensityToggle`	`boolean`	—	Show a comfortable/compact density toggle in the toolbar.
`enableCsvExport`	`boolean`	—	Show a CSV export button in the toolbar.
`csvFileName`	`string`	—	Download file name (without extension). Defaults to "export".
`loading`	`boolean`	—	Render skeleton rows instead of data.
`loadingRowCount`	`number`	—	Number of skeleton rows while `loading`. Defaults to the page size or 5.
`error`	`ReactNode`	—	Render an error state with an optional retry button.
`onRetry`	`() => void`	—	Called when the error-state retry button is pressed.
`emptyState`	`ReactNode`	—	Custom empty-state content. Defaults to "No results.".
`className`	`string`	—	Class applied to the outer wrapper.
`toolbarLabel`	`string`	—	Accessible label for the toolbar region. Defaults to "Table controls".

DataTableColumnHeaderProps

Prop	Type	Default	Description
`column`*	`Column<TData, TValue>`	—	—
`title`*	`string`	—	—
`className`	`string`	—	—