# Data Tables

> Compose reusable shadcn tables with typed columns, readable cells and server-owned navigation.

*Canonical: https://makerkit.dev/docs/void-cloudflare/development-guide/data-tables*

---

`@kit/ui/data-table` supplies a consistent table frame and independently reusable cells. It takes your rows, columns, translated copy and callbacks. Your app owns queries, authorization and navigation; the component never sorts a server page locally.

Admin user and organization lists count matching rows separately, then clamp and read the requested page. Both queries share the same filters. This lets indexed page reads stop at their limit; exact counts still scan matches. Concurrent changes may briefly make a total differ from the rows displayed.

## A Customer Table

```tsx
import {
  DataTable,
  NumberCell,
  StatusCell,
  type DataTableLabels,
  type TableColumn,
  type TableColumnLabels,
} from '@kit/ui/data-table';

type Order = { id: string; name: string; total: number; status: string };
type Props = {
  rows: Order[];
  caption: string;
  labels: DataTableLabels;
  columnLabels: TableColumnLabels;
  preferenceScope?: string;
  headings: { name: string; total: string; status: string };
};

export function OrdersTable({ rows, caption, labels, headings, columnLabels, preferenceScope }: Props) {
  const columns: TableColumn<Order>[] = [
    { id: 'name', header: headings.name, hideable: false, cell: (row) => row.name },
    {
      id: 'total',
      header: headings.total,
      align: 'end',
      cell: (row) => <NumberCell value={row.total} options={{ style: 'currency', currency: 'USD' }} />,
    },
    {
      id: 'status',
      header: headings.status,
      cell: (row) => <StatusCell>{row.status}</StatusCell>,
    },
  ];

  return <DataTable rows={rows} rowKey={(row) => row.id} columns={columns} caption={caption} labels={labels} columnLabels={columnLabels} preferencesKey={preferenceScope} />;
}
```

Provide `empty`, `loading`, `failed`, `retry`, `sortAscending` and `sortDescending` through `DataTableLabels`. Column IDs and row IDs must be stable and unique. Values remain React text; permission-aware links belong in your cell renderers.

## Frame and Navigation

Use `toolbar` for your search/filter controls and `footer` for navigation. Existing [TableFilters](./shared-utilities#table-filters) can occupy the toolbar. Pass `status="loading"` to announce refreshes while keeping existing rows visible, or `status="error"` with an optional `onRetry` callback.

`DataTablePagination` has two modes:

- `offset`: a real range/count summary, previous/next destinations and optional page-size choices.
- `cursor`: a loaded-row summary, next/first destinations and no page-size or artificial page-count controls.

Destinations contain either `href` or `onClick`. Supply `renderLink` when using hrefs; bind it to your framework's Link. Page-size choices contain their own destinations. Server links must preserve filters and reset the page/cursor when sort or size changes. Cursor APIs keep their own bounded page size.

Columns opt into sorting with `sort: { direction, ascending, descending }`. The table displays the current direction and follows the supplied destination. Your server must validate sort fields and directions, sort the complete result set and break ties deterministically. Leave `sort` absent for unsupported columns.

## Cell Building Blocks

All cells can be used separately in your own shadcn `Table`:

| Component | Purpose |
|---|---|
| `TextCell` | Truncated text; optional `previewLabel` enables a keyboard-accessible full-value popover for values that may be clipped |
| `IdCell` | Shortened ID and explicit copy button; provide copy/copied/failed labels |
| `StatusCell` | Neutral, success, warning or critical badge |
| `BooleanCell` | Icon plus translated yes/no text |
| `NumberCell` | Locale-aware numbers/currency with tabular digits and right alignment |
| `DateCell` | Semantic time, supplied short label and exact UTC description; ISO date-only/zone-less inputs use UTC, with no relative client clock |
| `LinkCell` | Primary linked label and optional secondary detail; supply the actual authorized link as children |

The package supplies no row selection, row action menus, saved views or inline editing.

## Columns and Sticky Layout

Pass `columnLabels` (`TableColumnLabels`) to enable the searchable Columns popover and Sort menu. Labels include `columns`, `searchColumns`, `noColumns`, `resetColumns`, `pinLeft`, `pinRight`, `unpin`, `showColumn`, `hideColumn` and `sort`. A column with `hideable: false` stays visible; `pinnable: false` omits its pin controls. At least one column stays visible.

The table provides one bounded scroll viewport, sticky headings and left/right pinning. Declared column widths provide the initial layout; actual header widths determine pin offsets as the viewport changes. When pinned columns would cover a narrow viewport, horizontal pinning pauses so every column remains reachable; preferences resume on wider screens. Set `stickyHeader={false}` to opt out of sticky headings.

Use `defaultView={{ hidden: [], left: ['name'], right: [] }}` for initial presentation. Reset restores this default. Hidden pinned columns retain their pin preference and return to that edge when shown again.

Preferences are optional. Set `preferencesKey` to an app-owned user/table scope, for example `orders:${signedInUserId}`. Only versioned column IDs are stored. Initial server rendering/hydration uses defaults, then browser preferences load. Blocked/corrupt storage falls back safely, and unknown or no-longer-permitted columns are discarded. Never put row data, names or filters into the key or stored preferences.

Alternatively, supply `view` and `onViewChange` to own presentation completely; do not also supply `preferencesKey` or `defaultView`. Column presentation never controls authorization: only send columns/rows that the viewer may read.


## Deferred Page Data

For streamed/deferred rows, `DataTableFrame` can keep search/filter controls mounted while the table body swaps its loading and ready states. Put the stable toolbar on the frame and give the inner `DataTable` `className="rounded-none border-0"`. `emptyState` and `errorState` slots support application-specific onboarding or recovery instructions; `tableTestId` and row data attributes support browser verification.

The kit's Users, Organizations, Jobs and Audit pages are working consumer examples. Their adapters live in `packages/admin/src/ui/`, while app loaders own authorized projections, translated copy, preference scope and sort/pagination URLs. Jobs/Audit retain bounded cursors; Audit deliberately exposes no sort controls.
