DataTable

Accessible data table with typed columns, three-state sortable headings, optional row selection and pagination, and density variants. Composes the Table primitives and the useTable* hooks.

Status: beta. Group: data-display. Markdown version: /design-system/components/data-table.md

When to use

Use DataTable for structured records that users need to compare, sort, or select. Provide stable row identifiers and a meaningful caption.

When not to use

Do not use it for page layout.
Do not omit a meaningful caption.
Do not use unstable row indexes as identifiers.
Do not use DataTable as a page-layout grid or a visual card collection.

Look-alikes

The contract names no look-alike with a deciding condition.

Props

DataTable props
Prop	Type	Default	Description	Required
`data`	`Row[]`	none	Table rows.	Yes
`columns`	`DataTableColumn<Row>[]`	none	Ordered column definitions.	Yes
`getRowId`	`(row: Row) => string`	none	Stable row identifier.	Yes
`caption`	`string`	none	Accessible table name rendered as a caption.	Yes
`hideCaption`	`boolean`	`false`	Visually hides the caption while retaining the accessible name.	No
`sort`	`DataTableSort \| null`	none	Controlled sort state.	No
`defaultSort`	`DataTableSort \| null`	`null`	Initial uncontrolled sort state.	No
`onSortChange`	`(sort: DataTableSort \| null) => void`	none	Receives sort changes.	No
`selectedRowIds`	`string[]`	none	Controlled selected row identifiers; enables selection.	No
`defaultSelectedRowIds`	`string[]`	none	Initial uncontrolled selection; also enables selection.	No
`onSelectionChange`	`(rowIds: string[]) => void`	none	Receives selected row identifiers; also enables selection.	No
`getRowLabel`	`(row: Row) => string`	none	Accessible row label used by selection checkboxes.	No
`pageSize`	`number`	none	Rows per page; enables pagination when set.	No
`emptyState`	`React.ReactNode`	No data	Empty-state cell content.	No
`striped`	`boolean`	`false`	Alternating row surfaces.	No
`stickyHeader`	`boolean`	`false`	Pin the header row while the body scrolls.	No
`size`	`"sm" \| "md" \| "lg"`	`md`	Density scale.	No
`className`	`string`	none	No description in the contract.	No

Variants

Available sizes: sm, md, lg (default md).
Allowed striped values: true, false (default false).

Invalid combinations

MUST NOT: sort and defaultSort set together. sort makes the component controlled and defaultSort uncontrolled; pass one, not both.
MUST NOT: selectedRowIds and defaultSelectedRowIds set together. selectedRowIds makes the component controlled and defaultSelectedRowIds uncontrolled; pass one, not both.

Keyboard

DataTable keyboard behaviour
Key	Behaviour
Tab	Moves focus to the control and on to the next focusable element. (standard)
Space	Activates or toggles the focused control. (standard)
Enter	Activates the focused control. (standard)

Rows marked (standard) name a key the contract lists without a description; the behaviour shown is the usual one for that key.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

DataTable rules
Level	Rule	How it is checked
MUST NOT	`sort` and `defaultSort` set together. `sort` makes the component controlled and `defaultSort` uncontrolled; pass one, not both.	Checked by the MCP tool validate_component_usage.
MUST NOT	`selectedRowIds` and `defaultSelectedRowIds` set together. `selectedRowIds` makes the component controlled and `defaultSelectedRowIds` uncontrolled; pass one, not both.	Checked by the MCP tool validate_component_usage.
MUST	ARIA: Native table, thead, tbody, th and td semantics.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Caption supplies the accessible table name.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Sortable headings expose aria-sort.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Selection uses labelled native checkboxes.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	Required stories produce no axe violations at the configured severity.	Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8.
MUST	The accessibility tree (role, name, state) matches the committed snapshot for every required story.	Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2.
MUST	The component remains legible and operable under a real browser forced-colors: active pass.	Automated by `npm run test:stories:hc`.
MUST	Every documented keyboard interaction works as specified.	Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2.
MUST	A human completed an end-to-end accessibility review of this component.	Manual review, last on 2026-07-26.
SHOULD	Give every table a concise caption that explains what its rows represent.	Not stated in the contract.
SHOULD	Use stable domain identifiers so selection survives sorting and data refreshes.	Not stated in the contract.
SHOULD	Make a column sortable only when its values have an understandable order.	Not stated in the contract.
SHOULD	Keep cell content concise and move detailed content into a dedicated view.	Not stated in the contract.
SHOULD NOT	Do not hide row actions until pointer hover; keyboard users must find them too.	Not stated in the contract.

Install and import

Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
Import: import { DataTable } from "@digitaltableteur/react";
Entry point: @digitaltableteur/react/content exports it too.
Styles: import @digitaltableteur/react/style.css once at the app boundary.