# Table

A styled data table with caption, header, footer, alignment and row states.

```ehtml Example
import { Table, TableCaption, TableHead, TableCell, rowState } from "@elements/ui/table";

<Table label="Invoices">
  <table>
    <TableCaption>A list of your recent invoices.</TableCaption>
    <thead>
      <tr>
        <TableHead>Invoice</TableHead>
        <TableHead align="end">Amount</TableHead>
      </tr>
    </thead>
    <tbody>
      <tr e:for={inv of invoices} e:key={(i) => i.id} data-state={rowState(inv.selected)}>
        <TableCell>{inv.id}</TableCell>
        <TableCell align="end">{inv.amount}</TableCell>
      </tr>
    </tbody>
  </table>
</Table>
```

## Parts

| Part | What it is |
|---|---|
| `Table` | .table-container: the scroll container and the look for the native `<table>` inside. |
| `TableCaption` | `<caption>`: names the table. |
| `TableHead` | `<th>` with scope. |
| `TableCell` | `<td>`. |
| `thead, tbody, tfoot, tr` | Native elements, styled by the container: header rule, row rules, tinted footer, hover and selected rows. |
| `rowState(selected)` | "selected" or undefined, for a row's data-state. |
| `[role=table] in the container` | APG's div table: rowgroup, row, columnheader, rowheader and cell styled as the native sections and cells. |

## Attributes

### Table

| Attribute | Type | Default | Description |
|---|---|---|---|
| `label` | `string` | `""` | Names the scroll container as a region and makes it keyboard scrollable. |
| `class` | `string` | `""` | Extra classes on the container. |
| `attrs` | `Record<string, string \| number \| boolean \| undefined>` | `{}` | Other attributes for the container. |

### TableCaption

| Attribute | Type | Default | Description |
|---|---|---|---|
| `side` | `"top" \| "bottom"` | `"bottom"` | Caption above or below. |

### tr

| Attribute | Type | Default | Description |
|---|---|---|---|
| `data-state` | `"selected" \| undefined` | `undefined` | On a native `<tr>`: rowState(row.selected) gives it the selected fill. |

### TableHead, TableCell

| Attribute | Type | Default | Description |
|---|---|---|---|
| `align` | `"start" \| "center" \| "end"` | `"start"` | end aligns numbers to the inline end with tabular figures. |
| `colspan` | `number` | `1` | Columns spanned. |
| `rowspan` | `number` | `1` | Rows spanned. |

### TableHead

| Attribute | Type | Default | Description |
|---|---|---|---|
| `scope` | `"col" \| "row" \| "colgroup" \| "rowgroup"` | `"col"` | What the header cell labels. |

### every part

| Attribute | Type | Default | Description |
|---|---|---|---|
| `class` | `string` | `""` | Extra classes. |

## Slots

| Slot | Part | Content |
|---|---|---|
| `default` | `Table` | The native `<table>`. |
| `default` | `TableCaption, TableHead, TableCell` | The content. |

## Keyboard

| Keys | Action |
|---|---|
| `Tab` | Moves through controls in cells. With label, the table is a stop that scrolls sideways with the arrow keys. |

## Data attributes

| Attribute | Values | On |
|---|---|---|
| `data-state` | `"selected"` | tr |
| `data-align` | `"center" \| "end"` | TableHead, TableCell |
| `data-side` | `"top" \| "bottom"` | TableCaption |

## Accessibility

- Native table elements: the caption names the table and th scope ties headers to cells.
- label turns the scroll container into a named region a keyboard can focus and scroll; it is a tab stop only while its content overflows.
- APG's table of ARIA roles on divs (role=table, rowgroup, row, columnheader, cell) takes the same look inside the container.
- A selected row is styled only; the checkbox in it is what assistive tech reads.
- Hover and selection change the row fill, never a cell's size.

## See also

- [Badge](badge): A small label for a status, a count or a category, built on the pill.
- [Card](card): A surface with a header, body and footer, built on the base card styles.
- [Alert](alert): A callout that draws attention to a message, with an icon, a title and an action.
- [Icon](icon): An inline stroke icon from the set the templates draw their own controls with, sized in pixels and colored by the text around it.
- [Kbd](kbd): A keyboard key or shortcut, as text.
- [Separator](separator): A horizontal or vertical rule between content, semantic or decorative.