# 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

- 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 | Default | Description |
| --- | --- | --- | --- |
| `layout` | `TableLayout` | `'auto'` | `auto` sizes columns to content; `fixed` uses the column widths. |
| `minWidth` | `string` |  | A CSS length below which the table scrolls instead of shrinking. |
| `selectionMode` | `'none' \| 'single' \| 'multiple'` | `'none'` | `none`, `single` or `multiple`. |
| `selection` | `string[]` |  | Selected row values, when controlled. |
| `defaultSelection` | `string[]` | `[]` | Selected row values on mount. |
| `onSelectionChange` | `(selection: string[]) => void` |  | Called with the new selection. |
| `expanded` | `string[]` |  | Expanded row values, when controlled. |
| `defaultExpanded` | `string[]` | `[]` | Expanded row values on mount. |
| `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` | `null` | Sort on mount. |
| `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 | Default | 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 | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Identifies the column in the sort state. |
| `sortable` | `boolean` | `false` | Sorts by this column on activation. Needs `value`. |
| `rowHeader` | `boolean` | `false` | Renders this column's cells as row headers that name their rows. |
| `align` | `TableAlign` | `'start'` | `start`, `center` or `end`. |
| `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 | Default | 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 | Default | 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` | `false` | Removes the row from navigation, selection and its action. |
| `expandable` | `boolean` | `false` | Lets the row expand before its children are loaded. |

### 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 | Default | Description |
| --- | --- | --- | --- |
| `align` | `TableAlign` | `'start'` | `start`, `center` or `end`. |
| `sticky` | `TableSticky` |  | `start` or `end` pins the cell while the table scrolls sideways. |
| `noWrap` | `boolean` | `false` | Keeps the content on one line. |

### 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 | Default | 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 | Default | 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 | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` |  | Required. 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>
```

## Related

- [Checkbox](/docs/components/checkbox.md)
- [Skeleton](/docs/components/skeleton.md)
- [EmptyState](/docs/components/empty-state.md)
- [ScrollArea](/docs/components/scroll-area.md)
