Data table

Canonical specification

Purpose

A table the user works in: selects rows, sorts, resizes columns. The plain table is for reading; this component adds the controls and the keyboard model. It stays a native table so its cells keep their header associations; hosts that need cell-level navigation promote it to a grid and record the change.

Anatomy

The table component’s structure with the same rule, dividers and fills, plus: a selection column whose header holds a select-all with aria-checked true, false or mixed, drawn on color.action.primary.bg with the ✓ or – glyph in color.action.primary.text; native checkboxes in each row on color.surface.input with a 1px color.border.control boundary; rows that can take focus; and in the resizable variant a 1px handle in color.border.default at the inline end of each header that turns color.border.active under the pointer.

States

Precedence: loading > empty; selected > hover; focus-visible is always drawn. Selection is a fill; focus is a ring; they never borrow each other’s form.

Keyboard

Header controls first: the select-all, then each sort button. Rows use a roving tabindex so the body costs one tab stop; Up and Down move, Space toggles, Shift extends, Ctrl+A selects all. Controls inside the focused row are reached with Tab and left with Shift+Tab. Column widths are set from a header menu or by dragging the handle; the handle itself is never a tab stop.

Accessibility

Every row checkbox is labelled by the row’s first data cell (aria-labelledby); the select-all is named “Select all rows” and exposes aria-checked="mixed" when only some are selected. aria-selected on the row mirrors its checkbox. Sorted headers carry aria-sort; the table carries aria-busy while loading; the count of selected rows is announced through a live region owned by the surrounding toolbar. Contrast: text 8.43:1, header 10.10:1, selected text 12.47:1 on the fill, ring 4.57:1 on the surface and 7.48:1 on the fill, checkbox boundary 4.33:1, check glyph 9.28:1 on the primary fill. Checkboxes and handles are at least 24 CSS pixels tall in compact density.

Portability

The table component’s drawing plus a checkbox column and a header checkbox; the handle is a 1px rule. Toolkits with native table views map row selection to their selection model and the mixed state to their tristate checkbox. Hosts without row focus fall back to the checkbox as the only row control and record it.

Non-examples

A grid role on a table that is not navigated cell by cell. Zebra stripes. A select-all that is a native checkbox with a script-only indeterminate state and no aria-checked. Rows selected by clicking anywhere with no checkbox alternative. A selected row shown by a border alone. A resize handle that is a tab stop. An animated loading skeleton. Rounded checkboxes. Text truncated with no full-value affordance.