# 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

- 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 | Default | Description |
| --- | --- | --- | --- |
| `selectionMode` | `TableSelectionMode` | `'none'` | How many rows can be selected. |
| `selection` | `string[]` |  | The selected row values, when controlled. |
| `defaultSelection` | `string[]` | `[]` | The selected row values on mount, when uncontrolled. |
| `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. |
| `onExpandedChange` | `(expanded: string[]) => void` |  | Called with the new expanded row values. |
| `sort` | `TableSort \| null` |  | The sorted column and direction, when controlled. |
| `defaultSort` | `TableSort \| null` | `null` | The sorted column and direction on mount, when uncontrolled. |
| `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 | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Identifies the column in `sort`. |
| `sortable` | `boolean` | `false` | Sorts ascending on activation, then flips. Needs `value`. |
| `rowHeader` | `boolean` | `false` | Renders this column’s cells as `th scope="row"` that name their rows. |

### Table.Body

A `tbody` that renders a row per visible item, children after their expanded parent.

| Prop | Type | Default | 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 | Default | 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` | `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.

### 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>
```
