Skip to content
Mosaic
On this page

Table

A styled native table with optional row actions, selection, sorting and expandable tree rows, over the headless Table primitive. Table.Root owns the selection, expanded and sort state, and scrolls sideways when wider than its container. With actions, selection, sorting or tree rows it becomes a grid or treegrid with one tab stop and arrow-key navigation.

Use for

  • a data table, such as members or invitations
  • rows that open a page or run an action on click
  • selectable rows with a select-all checkbox
  • sortable columns
  • expandable rows with child rows, such as logs
  • a search box above a table

Practices

GuidancePractice
DoName the table with aria-label or aria-labelledby on Table.Root.
DoMark the column that names each row with rowHeader, so rows and their checkboxes take that name.
DoSort the items yourself or on the server. The table only tracks the sort state.
DoPass onClick or href to Table.Row for a row action, instead of a link or button in a cell.
Don’tRender Table.Row outside the children function of Table.Body. It throws.
Don’tUnmount rows while the next page loads. Turn them into bones with Skeleton (mosaic guides inspect skeletons).

API reference

Table.Root

Renders the table inside a shell (cl-table-shell) and a focusable horizontal scroll viewport (cl-table-viewport). Carries data-layout.

Slot: cl-table

PropTypeDescription
layoutTableLayoutauto sizes columns to content; fixed uses the column widths.Default: 'auto'
minWidthstringA CSS length below which the table scrolls instead of shrinking.
selectionMode'none' | 'single' | 'multiple'none, single or multiple.Default: 'none'
selectionstring[]Selected row values, when controlled.
defaultSelectionstring[]Selected row values on mount.Default: []
onSelectionChange(selection: string[]) => voidCalled with the new selection.
expandedstring[]Expanded row values, when controlled.
defaultExpandedstring[]Expanded row values on mount.Default: []
onExpandedChange(expanded: string[]) => voidCalled when a row expands or collapses.
sort{ column: string; direction: 'ascending' | 'descending' } | null{ column, direction }, when controlled.
defaultSort{ column: string; direction: 'ascending' | 'descending' } | nullSort on mount.Default: null
onSortChange(sort: { column: string; direction: 'ascending' | 'descending' }) => voidCalled when a sortable column is activated.

Table.Toolbar

A div above the table for search and actions.

Slot: cl-table-toolbar

A search input with a magnifying glass and a clear button while it has a value. Takes Input props.

Slot: cl-table-search

PropTypeDescription
labelstringAccessible name and placeholder.
clearLabelstringAccessible name of the clear button.
valuestringThe query. Always controlled.
onValueChange(value: string) => voidCalled with the new query. Clearing calls it with an empty string and refocuses the input.

Table.Header

The thead, wrapping its columns in a tr.

Slot: cl-table-header

Table.Column

A th scope="col". A sortable one shows a sort icon and carries data-sortable and data-sort-direction. Carries data-align and data-sticky.

Slot: cl-table-column

PropTypeDescription
valuestringIdentifies the column in the sort state.
sortablebooleanSorts by this column on activation. Needs value.Default: false
rowHeaderbooleanRenders this column's cells as row headers that name their rows.Default: false
alignTableAlignstart, center or end.Default: 'start'
stickyTableStickystart or end pins the column while the table scrolls sideways.
widthstringA fixed CSS width.

Table.Body

The tbody. Renders a row per visible item, or the empty state in one cell (cl-table-empty).

Slot: cl-table-body

PropTypeDescription
itemsreadonly Item[]The records to render.
itemToStringValue(item: Item) => stringThe row's value in the selection and expanded state.
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.ReactNodeRendered in one cell spanning every column when there are no items.

Table.Row

A tr. Carries data-selected, data-disabled, data-expanded and data-actionable, and --table-row-depth in a tree.

Slot: cl-table-row

PropTypeDescription
onClickReact.MouseEventHandler<HTMLTableRowElement>Row action, run on click and Enter. Clicks on controls inside the row do not run it.
hrefstringRow link. Keeps modifier keys, so Cmd or Ctrl-click opens a new tab.
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. Carries data-align, data-sticky and data-no-wrap.

Slot: cl-table-cell

PropTypeDescription
alignTableAlignstart, center or end.Default: 'start'
stickyTableStickystart or end pins the cell while the table scrolls sideways.
noWrapbooleanKeeps the content on one line.Default: false

Table.SelectionColumn

A header cell with a Checkbox that selects all visible, enabled rows. Indeterminate when some are selected.

Slot: cl-table-select-cell

PropTypeDescription
aria-labelstringRequired. There is no row header to name it.

Table.SelectionCell

A body cell with a Checkbox that selects its row.

Slot: cl-table-select-cell

PropTypeDescription
aria-labelstringRequired. Read before the row header, so 'Select' reads as "Select <row>".

Table.ExpandButton

A chevron button that toggles its row's children. Renders only when the row can expand. Out of the tab order; the arrow keys expand and collapse. Carries data-expanded or data-collapsed.

Slot: cl-table-expand-button

PropTypeDescription
aria-labelstringRequired. Read before the row header.

Examples

Selectable rows

TSX
<Table.Root aria-label='Members' selectionMode='multiple'>
  <Table.Header>
    <Table.SelectionColumn aria-label='Select all' />
    <Table.Column value='name' rowHeader>Name</Table.Column>
  </Table.Header>
  <Table.Body items={members} itemToStringValue={member => member.id} renderEmptyState={() => m.empty}>
    {member => (
      <Table.Row>
        <Table.SelectionCell aria-label='Select' />
        <Table.Cell>{member.name}</Table.Cell>
      </Table.Row>
    )}
  </Table.Body>
</Table.Root>

A search toolbar

TSX
<Table.Toolbar>
  <Table.Search label={m.search} clearLabel={m.clear} value={query} onValueChange={setQuery} />
</Table.Toolbar>