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
| Guidance | Practice |
|---|---|
| Do | Name the table with aria-label or aria-labelledby on Table.Root. |
| Do | Mark the column that names each row with rowHeader, so rows and their checkboxes take that name. |
| Do | Sort the items yourself or on the server. The table only tracks the sort state. |
| Do | Pass onClick or href to Table.Row for a row action, instead of a link or button in a cell. |
| Don’t | Render Table.Row outside the children function of Table.Body. It throws. |
| Don’t | Unmount 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
| Prop | Type | Description |
|---|---|---|
layout | TableLayout | auto sizes columns to content; fixed uses the column widths.Default: 'auto' |
minWidth | string | A CSS length below which the table scrolls instead of shrinking. |
selectionMode | 'none' | 'single' | 'multiple' | none, single or multiple.Default: 'none' |
selection | string[] | Selected row values, when controlled. |
defaultSelection | string[] | Selected row values on mount.Default: [] |
onSelectionChange | (selection: string[]) => void | Called with the new selection. |
expanded | string[] | Expanded row values, when controlled. |
defaultExpanded | string[] | Expanded row values on mount.Default: [] |
onExpandedChange | (expanded: string[]) => void | Called when a row expands or collapses. |
sort | { column: string; direction: 'ascending' | 'descending' } | null | { column, direction }, when controlled. |
defaultSort | { column: string; direction: 'ascending' | 'descending' } | null | Sort on mount.Default: null |
onSortChange | (sort: { column: string; direction: 'ascending' | 'descending' }) => void | Called when a sortable column is activated. |
Table.Toolbar
A div above the table for search and actions.
Slot: cl-table-toolbar
Table.Search
A search input with a magnifying glass and a clear button while it has a value. Takes Input props.
Slot: cl-table-search
| Prop | Type | Description |
|---|---|---|
label | string | Accessible name and placeholder. |
clearLabel | string | Accessible name of the clear button. |
value | string | The query. Always controlled. |
onValueChange | (value: string) => void | Called 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
| Prop | Type | Description |
|---|---|---|
value | string | Identifies the column in the sort state. |
sortable | boolean | Sorts by this column on activation. Needs value.Default: false |
rowHeader | boolean | Renders this column's cells as row headers that name their rows.Default: false |
align | TableAlign | start, center or end.Default: 'start' |
sticky | TableSticky | start or end pins the column while the table scrolls sideways. |
width | string | A 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
| Prop | Type | Description |
|---|---|---|
items | readonly Item[] | The records to render. |
itemToStringValue | (item: Item) => string | The row's value in the selection and expanded state. |
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 | Rendered 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
| Prop | Type | Description |
|---|---|---|
onClick | React.MouseEventHandler<HTMLTableRowElement> | Row action, run on click and Enter. Clicks on controls inside the row do not run it. |
href | string | Row link. Keeps modifier keys, so Cmd or Ctrl-click opens a new tab. |
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. Carries data-align, data-sticky and data-no-wrap.
Slot: cl-table-cell
| Prop | Type | Description |
|---|---|---|
align | TableAlign | start, center or end.Default: 'start' |
sticky | TableSticky | start or end pins the cell while the table scrolls sideways. |
noWrap | boolean | Keeps 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
| Prop | Type | Description |
|---|---|---|
aria-label | string | Required. 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
| Prop | Type | Description |
|---|---|---|
aria-label | string | Required. 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
| Prop | Type | Description |
|---|---|---|
aria-label | string | Required. Read before the row header. |
Examples
Selectable rows
<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
<Table.Toolbar>
<Table.Search label={m.search} clearLabel={m.clear} value={query} onValueChange={setQuery} />
</Table.Toolbar>