Skip to content
Mosaic
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

GuidancePractice
DoMark the column that names each row with rowHeader. Rows, checkboxes and expand buttons take their names from it.
DoGive the header Table.SelectionCheckbox an aria-label. It has no row header to name it.
DoSort items yourself, or on the server, from sort. The table does not reorder rows.
DoIndent tree rows with --table-row-depth.
Don’tPut a link or button in a cell to make the row clickable. Pass href or onClick to Table.Row instead.
Don’tRender 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.

PropTypeDescription
selectionModeTableSelectionModeHow many rows can be selected.Default: 'none'
selectionstring[]The selected row values, when controlled.
defaultSelectionstring[]The selected row values on mount, when uncontrolled.Default: []
onSelectionChange(selection: string[]) => voidCalled with the new selected row values.
expandedstring[]The expanded row values, when controlled.
defaultExpandedstring[]The expanded row values on mount, when uncontrolled.Default: []
onExpandedChange(expanded: string[]) => voidCalled with the new expanded row values.
sortTableSort | nullThe sorted column and direction, when controlled.
defaultSortTableSort | nullThe sorted column and direction on mount, when uncontrolled.Default: null
onSortChange(sort: TableSort) => voidCalled 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.

PropTypeDescription
valuestringIdentifies the column in sort.
sortablebooleanSorts ascending on activation, then flips. Needs value.Default: false
rowHeaderbooleanRenders 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.

PropTypeDescription
itemsreadonly Item[]The records, one row each.
itemToStringValue(item: Item) => stringThe row value used in selection and expanded.
itemToChildren(item: Item) => readonly Item[] | undefinedAn item’s child items. Makes the table a tree grid.
children(item: Item) => React.ReactNodeRenders the Table.Row for an item.
renderEmptyState() => React.ReactNodeContent 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.

PropTypeDescription
onClickReact.MouseEventHandler<HTMLTableRowElement>The row action, run on click and Enter. Clicks on controls inside the row do not run it.
hrefstringOpens this link as the row action, keeping modifier keys. onClick runs first and can cancel it.
disabledbooleanRemoves the row from navigation, selection and its action.Default: false
expandablebooleanLets 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

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