On this page
Table
Headless, unstyled native <table> with optional row actions, selection, sorting and expandable tree rows. Becomes a grid or treegrid with one tab stop and arrow-key navigation only when one of those is in use.
Use for
- a data table whose rows open a page or run an action
- a table with selectable rows and a select-all checkbox
- a table with sortable columns
- a tree of expandable rows, such as logs with child entries
Practices
| Guidance | Practice |
|---|---|
| Do | Mark the column that names each row with rowHeader. Rows, checkboxes and expand buttons take their names from it. |
| Do | Give the header Table.SelectionCheckbox an aria-label. It has no row header to name it. |
| Do | Sort items yourself, or on the server, from sort. The table does not reorder rows. |
| Do | Indent tree rows with --table-row-depth. |
| Don’t | Put a link or button in a cell to make the row clickable. Pass href or onClick to Table.Row instead. |
| Don’t | Render Table.Row outside the Table.Body children function. It throws. |
API reference
Table.Root
A table that holds the selection, expanded rows and sort, and the keyboard navigation. Escape clears the selection and Ctrl+A selects all.
| Prop | Type | Description |
|---|---|---|
selectionMode | TableSelectionMode | How many rows can be selected.Default: 'none' |
selection | string[] | The selected row values, when controlled. |
defaultSelection | string[] | The selected row values on mount, when uncontrolled.Default: [] |
onSelectionChange | (selection: string[]) => void | Called with the new selected row values. |
expanded | string[] | The expanded row values, when controlled. |
defaultExpanded | string[] | The expanded row values on mount, when uncontrolled.Default: [] |
onExpandedChange | (expanded: string[]) => void | Called with the new expanded row values. |
sort | TableSort | null | The sorted column and direction, when controlled. |
defaultSort | TableSort | null | The sorted column and direction on mount, when uncontrolled.Default: null |
onSortChange | (sort: TableSort) => void | Called when a sortable column header is activated. |
Table.Header
A thead that wraps its columns in one tr.
Table.Column
A th scope="col". A sortable column carries aria-sort, data-sortable and data-sort-direction, and sorts on click, Enter or Space.
| Prop | Type | Description |
|---|---|---|
value | string | Identifies the column in sort. |
sortable | boolean | Sorts ascending on activation, then flips. Needs value.Default: false |
rowHeader | boolean | Renders this column’s cells as th scope="row" that name their rows.Default: false |
Table.Body
A tbody that renders a row per visible item, children after their expanded parent.
| Prop | Type | Description |
|---|---|---|
items | readonly Item[] | The records, one row each. |
itemToStringValue | (item: Item) => string | The row value used in selection and expanded. |
itemToChildren | (item: Item) => readonly Item[] | undefined | An item’s child items. Makes the table a tree grid. |
children | (item: Item) => React.ReactNode | Renders the Table.Row for an item. |
renderEmptyState | () => React.ReactNode | Content for one cell spanning every column while there are no items. |
Table.Row
A tr with aria-selected, and tree ARIA in a tree grid. Carries data-selected, data-disabled, data-expanded and data-actionable, and the --table-row-depth variable. Once any row is selected, a click toggles selection instead of the action.
| Prop | Type | Description |
|---|---|---|
onClick | React.MouseEventHandler<HTMLTableRowElement> | The row action, run on click and Enter. Clicks on controls inside the row do not run it. |
href | string | Opens this link as the row action, keeping modifier keys. onClick runs first and can cancel it. |
disabled | boolean | Removes the row from navigation, selection and its action.Default: false |
expandable | boolean | Lets the row expand before its children are loaded.Default: false |
Table.Cell
A td, or a th scope="row" in a rowHeader column.
Table.SelectionCheckbox
A checkbox that selects its row, or every selectable row inside Table.Header. Renders nothing when selection is off, and in the header unless multiple. Carries data-checked, data-indeterminate and data-disabled.
Table.ExpandButton
A button that toggles its row’s children, out of the tab order. Renders only when the row can expand. Carries data-expanded or data-collapsed.
Examples
Selectable rows that link
<Table.Root aria-label='Logs' selectionMode='multiple'>
<Table.Header>
<Table.Column>
<Table.SelectionCheckbox aria-label='Select all' />
</Table.Column>
<Table.Column value='message' rowHeader>Message</Table.Column>
</Table.Header>
<Table.Body items={logs} itemToStringValue={log => log.id}>
{log => (
<Table.Row href={`/logs/${log.id}`}>
<Table.Cell>
<Table.SelectionCheckbox aria-label='Select' />
</Table.Cell>
<Table.Cell>{log.message}</Table.Cell>
</Table.Row>
)}
</Table.Body>
</Table.Root>