Data Tables

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

@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

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 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:

ComponentPurpose
TextCellTruncated text; optional previewLabel enables a keyboard-accessible full-value popover for values that may be clipped
IdCellShortened ID and explicit copy button; provide copy/copied/failed labels
StatusCellNeutral, success, warning or critical badge
BooleanCellIcon plus translated yes/no text
NumberCellLocale-aware numbers/currency with tabular digits and right alignment
DateCellSemantic time, supplied short label and exact UTC description; ISO date-only/zone-less inputs use UTC, with no relative client clock
LinkCellPrimary 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.