Data Table
Columns, sorting, row selection, pagination, and the three states a table spends most of its life in (loading / empty / error). It composes primitives — Checkbox, Pagination, Skeleton, Button — so it is a pattern, not a primitive.
Preview
Rendered from the story the storybook (a11y) CI gate runs axe against — the preview can't show something that hasn't been verified.
Install
Two equivalent paths — the URL works in any shadcn-CLI setup; the alias works once you've registered @interlace in your components.json.
npx shadcn@latest add https://ds.interlace.tools/r/data-table.jsonnpx shadcn@latest add @interlace/data-tableBehavior
What this component does — the keyboard path, the measured colour, the text equivalent and the states it can be in. Every figure below is read out of the test or the source that enforces it by scripts/build-behavior-map.mjs, so nothing here can outlive the gate that keeps it true.
3 steps, 3 key presses — replayed on every PR by the play function of KeyboardSort. Axe cannot press a key, so this — not the a11y scan — is what proves the component is operable without a mouse.
- 1Enter sorts ascendingEnter
- 2a second press flips itEnter
- 3a third press returns the natural orderEnter
Measured contrast
packages/ui/__tests__/theme-contract-lock.test.ts ↗Every semantic colour pair this component's own source uses, measured against the shipped hexes in all 4 theme × scheme combinations. The tightest is muted-foreground on muted at 7.34:1 (harbor · light), against a floor of 4.5:1.
| Pair | interlacelight | interlacedark | harborlight | harbordark | Floor |
|---|---|---|---|---|---|
| muted-foreground on mutedcopy on a muted surface | 8.81:1 | 10.48:1 | 7.34:1 | 8.64:1 | 4.5:1SC 1.4.3 |
| destructive on backgrounddestructive tint on the page surface | 8.31:1 | 10.43:1 | 7.60:1 | 10.03:1 | 3.0:1SC 1.4.11 |
| muted-foreground on backgroundsecondary copy | 9.41:1 | 11.32:1 | 7.82:1 | 9.52:1 | 4.5:1SC 1.4.3 |
| destructive on carddestructive tint inside a card | 8.31:1 | 9.66:1 | 8.02:1 | 9.09:1 | 3.0:1SC 1.4.11 |
| muted-foreground on cardsecondary copy in a card | 9.41:1 | 10.48:1 | 8.25:1 | 8.64:1 | 4.5:1SC 1.4.3 |
| accent-foreground on accenthover/highlight face | 8.98:1 | 10.46:1 | 8.95:1 | 9.65:1 | 4.5:1SC 1.4.3 |
| foreground on backgroundbody copy | 19.65:1 | 16.97:1 | 17.74:1 | 16.19:1 | 4.5:1SC 1.4.3 |
Text pairs are held to 4.5:1 (WCAG 2.2 SC 1.4.3); borders, rings and chart axes to 3:1 (SC 1.4.11 non-text). Bold is the worst cell in the row — the one a brand fork has to keep an eye on.
Text equivalent
packages/ui/src/patterns/data-table.tsx ↗A chart's alt text is not a sentence about the chart — the equivalent of the data is the data. This is what a screen reader gets, read out of the source the install writes into your tree.
Ships sr-only copy for what the visual carries by position, colour or icon alone — a label, not a full data equivalent.
Runtime contract
packages/ui/vitest.config.ts ↗Where it renders, how narrow it survives, and whether its lines are inside the coverage gate — three answers a consumer needs before the paste, not after the bug.
- Render boundary
'use client'Hydrates. It brings JavaScript to any route that imports it — put the boundary here, not at the page.
- Minimum viewport
MIN_VIEWPORT = 320Declared, not assumed. Below 320 CSS px the preflight contract draws a dev-mode outline — how to switch it on.
- Coverage gate
not in the gateThe 100% gate currently covers
src/charts/**/*.{ts,tsx}andsrc/lib/**/*.{ts,tsx}andsrc/primitives/{button-variants,data-state-model,meter-scale,skeleton-variants}.tsandsrc/primitives/{alert,aspect-ratio,avatar,badge,box,breadcrumb,button,callout,card,checkbox,container,data-state,focus-ring,grade-badge,grid,input,label,meter,pagination,published-date,reading-time,section,section-boundary,separator,skip-link,stack,stat-strip,tag,textarea,typography,visually-hidden}.tsx. This file is outside it — the glob widens in phase 7.2.
History
This component is at v1.0.0, first shipped in @interlace/ui 1.1.0. The version is stamped as a banner into the file the install writes, so the copy in your tree says which one you have — compare it with the number above before deciding whether to re-run the install.
@interlace/ui 1.1.01 entry
- Addedminor
New
DataTablepattern — a real<table>with column definitions, sorting, row selection, pagination, and designed loading / empty / error states. Sort and selection are the caller's state (sort/onSortChange,selected/onSelectionChange), so the whole view can live in the query string and a sorted, paged, partly-selected table can be linked to a colleague. Selection is keyed by row id, so it survives sorting and paging. Semantics are the point:<caption>,<th scope="col">, one<th scope="row">per row,aria-sorton sortable headers, and a selection checkbox whose accessible name identifies the row. Pure logic (sort cycle, comparators, page-window, selection maths) ships alongside asdata-table-modeland is exported for callers wiring their own URL state. Skeleton gains adata-tablevariant — a header row plus body rows, so the loading state reserves the real silhouette instead of collapsing to a spinner. Not included, deliberately: filtering UI, column resize/reorder, virtualization, grouping.Components
Import
17 named exports — pull the parts you need.
import { DataTable, MIN_VIEWPORT, PageSelectionState, SortDirection, SortValue, ariaSortOf, clampPage, columnName, compareValues, nextSort, pageSelectionState, pageWindow, selectionMessage, sortActionLabel, sortRows, toggleKey, togglePageSelection } from '@/components/ui/patterns/data-table';API reference
Parsed from the type declarations in the source — the same file the install writes into your tree, so this table can't drift from the component you get.
DataTableProps
Also accepts every <div> attribute.
| Prop | Type | Description |
|---|---|---|
| columns* | readonly DataTableColumn<Row>[] | — |
| rows* | readonly Row[] | — |
| rowKey* | (row: Row) => string | Stable identity per row. Selection is keyed by this value, so it must survive sorting, paging and refetching — a database id, not an index. |
| caption* | string | The `<caption>`. Required: an unnamed table of numbers is a wall of numbers, and it is the first thing a screen reader reads. |
| captionHidden | boolean | Visually hides the caption (it stays in the accessibility tree). Use when a heading directly above already names the table. |
| rowLabel | (row: Row) => string | Human name of a row, used as the accessible name of its selection checkbox — "Select Ada Lovelace", never "Select". Defaults to `rowKey`, which is better than nothing and worse than a name. |
| sort | DataTableSort | null | Current sort, or `null` for the server's natural order. |
| onSortChange | (next: DataTableSort | null) => void | Receives the next sort on header activation (asc → desc → null). Omitting it leaves every header inert, whatever the columns declare. |
| selected | readonly string[] | Selected row keys — including keys that are not on the current page. Those survive untouched through "select page". |
| onSelectionChange | (next: string[]) => void | Omitting it removes the selection column entirely. |
| dense | boolean | Tighter row height for long tables. |
| loading | boolean | Paints `<Skeleton variant="data-table" />` instead of the table. |
| error | React.ReactNode | Error message. Replaces the BODY only — the header and the pager stay put, so the retry lands the reader back where they were. |
| onRetry | () => void | Renders a Retry button beside `error`. |
| empty | React.ReactNode | Shown in place of the body when `rows` is empty. Pass a different node for "no matches, clear filters" than for "nothing here yet" — they are different messages and only one of them is the reader's fault. |
| pagination | DataTablePaginationState | Wires the Pagination primitive under the table. |
| toolbar | React.ReactNode | Extra controls in the selection bar (bulk actions). |
Skeleton
Pass loading and the component renders a shape-matched <Skeleton /> in its own place — same box, so nothing reflows when the data lands. Below is the same story with loading={true}.
<DataTable loading={isPending} />Accessibility
Every story for this component is rendered headlessly and checked with axe-core (wcag2aa, wcag22aa, best-practice, ACT) on every PR. That gate has no continue-on-error, so what ships has zero known violations.
What follows is what static analysis can see. Axe cannot press a key and never sees an overlay open, so the operable-without-a-mouse claim lives in Behavior instead, where the keyboard path is replayed step by step.
- Focus + keyboard behaviour
- Native element semantics — no interaction layer to get wrong.
- Focus ring (WCAG 2.2 SC 2.4.13)
- Inherited from the preflight focus contract shipped in @interlace/theme.
- Reduced motion
- No animation to gate.
- ARIA in the source
role="alert"role="status"aria-disabledaria-labelaria-livearia-selectedaria-sort
Examples
11 more states from the same story file.
R-rule compliance
Every primitive in @interlace/ui models to the portable 26-rule floor enforced by the componentApi ESLint preset. The cells below pin exactly where each rule applies in this file.
| Rule | Concept | Where |
|---|---|---|
| R4 | Extends native el | `Omit<React.ComponentProps<'div'>, 'onSelect'>` |
| R6 | data-slot on every part | `data-table` / `-scroll` / `-head` / `-row` / `-pagination` |
| R7 | className merged + ...rest | `cn(...)` + `{...props}` |
| R8 | No `isXxx` | `loading`, `dense`, `selected`, `sort` |
| R10 | Composition seam | `columns[].cell`, `empty`, `error`, `toolbar` take nodes |
| R11 | One variable per part | the row owns selection; the head owns sort |
| R12 | Reuse over wrap | Checkbox / Pagination / Skeleton / Button are the primitives |
| R13 | Ecosystem first | zero new dependencies — no TanStack Table |
| R14 | Declares min viewport | `data-min-viewport={String(MIN_VIEWPORT)}` |
| R18 | Tailwind only | zero inline `style` |
| R19 | Tokens only | `border-border`, `bg-muted`, `text-muted-foreground` |
| R20 | AA contrast | selected row = `bg-accent`/`text-accent-foreground` (9.31:1 light, 9.85:1 dark) |
| R23 | No layout shift | `loading` paints `<Skeleton variant="data-table" />` |
| R25 | Client component | sort / selection handlers |
| R26 | A11y | table semantics + `aria-sort` + named checkboxes + live region |
Minimum viewport
This primitive declares MIN_VIEWPORT = 320 CSS px (DESIGN_PRINCIPLES #14). When mounted in a container narrower than this, the preflight contract draws a dev-mode outline so the regression is visible during local development.
<body data-interlace-dev>...</body>
Add the data-interlace-dev attribute to the body in development builds only — preflight then outlines any primitive whose container is below its declared data-min-viewport.
Dependencies
- Base UI primitive
- Native / no Base UI dependency
- Lucide icons
ArrowDownIconArrowUpIconChevronsUpDownIcon
- NPM dependencies
lucide-react
Source
The full implementation — components/ui/patterns/data-table.tsx once installed.
'use client';
import * as React from 'react';
// @interlace/data-table v1.0.0 — Interlace design system.
// Docs, props and live preview: https://ds.interlace.tools/c/data-table
// What changed since: https://ds.interlace.tools/c/data-table#history
// Generated banner — keep it, the upgrade diff reads this version.
/**
* @interlace/ui — DataTable
*
* Columns, sorting, row selection, pagination, and the three states a table
* spends most of its life in (loading / empty / error). It composes
* primitives — Checkbox, Pagination, Skeleton, Button — so it is a pattern,
* not a primitive.
*
* ## It is a real `<table>`
*
* Not a grid of divs. `<caption>` names it, `<th scope="col">` names each
…629 more lines…Registry JSON
The raw registry record — what the shadcn CLI fetches.