# Table
Rows and columns, on native table elements.
Source page: https://dinachi.dev/docs/components/table

## Installation
```bash
npx @dinachi/cli@latest add table
```
Adds to your project:
- `components/ui/table/table.tsx`
- `components/ui/table/index.ts`

## Usage
```tsx
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"

export function Orders({ orders }: { orders: { id: string; customer: string; total: string }[] }) {
  return (
    <Table>
      <TableHeader>
        <TableRow>
          <TableHead>Order</TableHead>
          <TableHead>Customer</TableHead>
          <TableHead numeric>Total</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {orders.map((o) => (
          <TableRow key={o.id}>
            <TableCell>{o.id}</TableCell>
            <TableCell>{o.customer}</TableCell>
            <TableCell numeric>{o.total}</TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  )
}
```

## Anatomy
```tsx
<Table>
  <TableCaption />
  <TableHeader>
    <TableRow>
      <TableHead />
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell />
    </TableRow>
  </TableBody>
  <TableFooter>
    <TableRow>
      <TableCell />
    </TableRow>
  </TableFooter>
</Table>
```
- `Table`: The `<table>`, inside a container that scrolls it sideways when it is wider than its parent.
- `TableHeader`: The `<thead>`. Hidden visually, not from screen readers, when the table stacks.
- `TableBody`: The `<tbody>`. Rows tint on hover.
- `TableFooter`: The `<tfoot>`, ruled off the body. Its last row is the total, in heavier type.
- `TableRow`: A `<tr>`.
- `TableHead`: A `<th>`. Scoped to its column in the header and to its row elsewhere.
- `TableCell`: A `<td>`.
- `TableCaption`: The `<caption>`, above the table. Names it for screen readers.

## Examples

### Invoice
Numeric columns, a caption, and totals in the footer. Below 768px each line stacks.
```tsx
import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableFooter,
  TableHead,
  TableHeader,
  TableRow,
} from '@/components/ui/table';

const lines = [
  { item: 'Merino jumper', variant: 'Charcoal, M', qty: 1, price: 118 },
  { item: 'Linen shirt', variant: 'Sand, L', qty: 2, price: 64 },
  { item: 'Wool scarf', variant: 'Rust', qty: 1, price: 38 },
  { item: 'Socks, 3 pack', variant: 'Grey marl', qty: 2, price: 15 },
];
const money = (n: number) => '£' + n.toLocaleString('en-GB', { minimumFractionDigits: 2 });

export function Example() {
  const total = lines.reduce((sum, l) => sum + l.qty * l.price, 0) + 4.95;
  return (
    <Table stack>
      <TableCaption>
        <span className="flex items-baseline justify-between">
          <span className="text-base font-semibold text-foreground">Invoice 2048</span>
          <span>Due 1 Dec 2026</span>
        </span>
      </TableCaption>
      <TableHeader>
        <TableRow>
          <TableHead>Item</TableHead>
          <TableHead numeric>Qty</TableHead>
          <TableHead numeric>Price</TableHead>
          <TableHead numeric>Amount</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {lines.map((l) => (
          <TableRow key={l.item}>
            <TableCell stack="title">
              {l.item}
              <span className="block text-xs font-normal text-muted-foreground">{l.variant}</span>
            </TableCell>
            <TableCell numeric stack="meta">
              {l.qty}<span className="@lg:hidden"> ×</span>
            </TableCell>
            <TableCell numeric stack="meta">{money(l.price)}</TableCell>
            <TableCell numeric stack="value">{money(l.qty * l.price)}</TableCell>
          </TableRow>
        ))}
      </TableBody>
      <TableFooter>
        <TableRow>
          <TableCell colSpan={3} className="text-muted-foreground">Delivery</TableCell>
          <TableCell numeric>{money(4.95)}</TableCell>
        </TableRow>
        <TableRow>
          <TableCell colSpan={3} className="text-muted-foreground">VAT included</TableCell>
          <TableCell numeric className="text-muted-foreground">{money(total / 6)}</TableCell>
        </TableRow>
        <TableRow>
          <TableCell colSpan={3}>Total</TableCell>
          <TableCell numeric>{money(total)}</TableCell>
        </TableRow>
      </TableFooter>
    </Table>
  );
}
```

### Compact
Compact rows without dividers, for dense figures where spacing groups the cells.
```tsx
import { Table, TableBody, TableCaption, TableCell, TableHead, TableHeader, TableRow } from '@/components/ui/table';

export function Example({ rows }: { rows: { region: string; requests: number; errors: number; p95: number }[] }) {
  return (
    <Table density="compact" dividers="none">
      <TableCaption>Requests by region, last 24 hours</TableCaption>
      <TableHeader>
        <TableRow>
          <TableHead>Region</TableHead>
          <TableHead numeric>Requests</TableHead>
          <TableHead numeric>Errors</TableHead>
          <TableHead numeric>p95</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {rows.map((r) => (
          <TableRow key={r.region}>
            <TableCell>{r.region}</TableCell>
            <TableCell numeric>{r.requests.toLocaleString()}</TableCell>
            <TableCell numeric>{r.errors.toFixed(2)}%</TableCell>
            <TableCell numeric>{r.p95} ms</TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  );
}
```

## Notes

### Phone and desktop
Without `stack`, a wide table scrolls sideways inside its container. With it, each row reads as a line item once the table is under 512px wide, wherever it sits: the `title` cell and the `value` cell on the first line, the `meta` cells under them, and the footer rows as label and figure. Give every body row one `title` and at most one `value`.

### Sorting, selection and large data
Table is the markup and the look. Sorting, row selection and virtualised rows build on it in their own components.

## API reference

### Table
The `<table>`, inside a container that scrolls it sideways when it is wider than its parent.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `density` | `"comfortable" \| "compact"` | `"comfortable"` | Row height: 48px or 36px. |
| `dividers` | `"rows" \| "none"` | `"rows"` | Lines between body rows. |
| `stack` | `boolean` | `false` | When the table is under 512px wide, each row becomes a block, its cells placed by their `stack` role. |
| `containerClassName` | `string` | - | Classes for the scrolling container. |
| `containerRef` | `Ref<HTMLDivElement>` | - | The scrolling container, for a virtualiser or a scroll listener. |

### TableHeader
The `<thead>`. Hidden visually, not from screen readers, when the table stacks.

Takes the props of the element it renders.

### TableBody
The `<tbody>`. Rows tint on hover.

Takes the props of the element it renders.

### TableFooter
The `<tfoot>`, ruled off the body. Its last row is the total, in heavier type.

Takes the props of the element it renders.

### TableRow
A `<tr>`.

Takes the props of the element it renders.

### TableHead
A `<th>`. Scoped to its column in the header and to its row elsewhere.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `numeric` | `boolean` | `false` | Right-aligns the name over a column of figures. |
| `stack` | `"title" \| "value" \| "meta"` | `"title"` | Where a row header goes when the table stacks. |

### TableCell
A `<td>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `numeric` | `boolean` | `false` | Right-aligned tabular figures, so a column reads as one figure. |
| `stack` | `"title" \| "value" \| "meta"` | `"meta"` | Where the cell goes when the table stacks. `title` and `value` share the first line; `meta` sits under them. |

### TableCaption
The `<caption>`, above the table. Names it for screen readers.

Takes the props of the element it renders.

## Accessibility
- The parts are native table elements, so screen readers announce rows, columns and headers.
- A stacked table sets the table roles on its parts, since browsers drop them once the parts stop displaying as a table.
- Header cells are scoped to their column, and `TableHead` in a body row to its row.
- Give the table a `TableCaption` or an `aria-label` so it is named.

## Source
`components/ui/table/table.tsx`
```tsx
import * as React from "react"
import { cn } from "@/lib/utils"

type Density = "comfortable" | "compact"
type Dividers = "rows" | "none"
type Section = "header" | "body" | "footer"
type StackRole = "title" | "value" | "meta"

interface TableContextValue {
  density: Density
  dividers: Dividers
  stack: boolean
}

const TableContext = React.createContext<TableContextValue>({ density: "comfortable", dividers: "rows", stack: false })
const SectionContext = React.createContext<Section>("body")

// Browsers drop a table's semantics once its parts stop displaying as table parts, so a
// stacked table names them explicitly.
const role = (stack: boolean, name: string) => (stack ? name : undefined)

export interface TableProps extends React.TableHTMLAttributes<HTMLTableElement> {
  /** Row height. Compact also suits nested or dense data. */
  density?: Density
  /** Lines between body rows. */
  dividers?: Dividers
  /**
   * When the table's container is under 512px wide, each row becomes a block, with cells
   * placed by their `stack` role, so nothing scrolls sideways.
   */
  stack?: boolean
  /** Classes for the element that scrolls the table sideways. */
  containerClassName?: string
  /** The element that scrolls the table, for a virtualiser or a scroll listener. */
  containerRef?: React.Ref<HTMLDivElement>
}

const Table = React.forwardRef<HTMLTableElement, TableProps>(
  ({ className, containerClassName, containerRef, density = "comfortable", dividers = "rows", stack = false, ...props }, ref) => {
    const context = React.useMemo(() => ({ density, dividers, stack }), [density, dividers, stack])
    return (
      <TableContext.Provider value={context}>
        <div
          ref={containerRef}
          data-slot="table-container"
          className={cn("relative w-full overflow-x-auto", stack && "@container", containerClassName)}
        >
          <table
            ref={ref}
            role={role(stack, "table")}
            data-slot="table"
            data-density={density}
            data-dividers={dividers}
            data-stack={stack || undefined}
            className={cn(
              "w-full border-separate border-spacing-0 text-[13px]",
              stack && "@max-lg:block @max-lg:text-[15px]",
              className
            )}
            {...props}
          />
        </div>
      </TableContext.Provider>
    )
  }
)
Table.displayName = "Table"

const TableHeader = React.forwardRef<HTMLTableSectionElement, React.HTMLAttributes<HTMLTableSectionElement>>(
  ({ className, ...props }, ref) => {
    const { stack } = React.useContext(TableContext)
    return (
      <SectionContext.Provider value="header">
        <thead
          ref={ref}
          role={role(stack, "rowgroup")}
          data-slot="table-header"
          // The stacked rows say what each value is, so the column names are left to screen readers.
          className={cn(stack && "@max-lg:sr-only", className)}
          {...props}
        />
      </SectionContext.Provider>
    )
  }
)
TableHeader.displayName = "TableHeader"

const TableBody = React.forwardRef<HTMLTableSectionElement, React.HTMLAttributes<HTMLTableSectionElement>>(
  ({ className, ...props }, ref) => {
    const { stack } = React.useContext(TableContext)
    return (
      <SectionContext.Provider value="body">
        <tbody
          ref={ref}
          role={role(stack, "rowgroup")}
          data-slot="table-body"
          className={cn(
            "[&>tr:last-child>td]:border-b-0 [&>tr:last-child>th]:border-b-0",
            "[&>tr:hover]:bg-muted/70",
            stack && "@max-lg:block",
            className
          )}
          {...props}
        />
      </SectionContext.Provider>
    )
  }
)
TableBody.displayName = "TableBody"

const TableFooter = React.forwardRef<HTMLTableSectionElement, React.HTMLAttributes<HTMLTableSectionElement>>(
  ({ className, ...props }, ref) => {
    const { stack } = React.useContext(TableContext)
    return (
      <SectionContext.Provider value="footer">
        <tfoot
          ref={ref}
          role={role(stack, "rowgroup")}
          data-slot="table-footer"
          className={cn(
            // The first row rules off the body; the last is the total. Stacked rows already
            // end on a divider, so the rule is for the table layout only.
            stack
              ? "md:[&>tr:first-child>*]:border-t md:[&>tr:first-child>*]:pt-1.5"
              : "[&>tr:first-child>*]:border-t [&>tr:first-child>*]:pt-1.5",
            "[&>tr:last-child]:text-sm [&>tr:last-child]:font-semibold",
            // A total with nothing above it already sits under the last row's divider.
            stack &&
              "@max-lg:grid @max-lg:gap-2.5 @max-lg:py-4 @max-lg:[&>tr:last-child:not(:first-child)]:border-t @max-lg:[&>tr:last-child]:pt-2 @max-lg:[&>tr:last-child]:text-lg",
            className
          )}
          {...props}
        />
      </SectionContext.Provider>
    )
  }
)
TableFooter.displayName = "TableFooter"

const TableRow = React.forwardRef<HTMLTableRowElement, React.HTMLAttributes<HTMLTableRowElement>>(
  ({ className, ...props }, ref) => {
    const { stack, density, dividers } = React.useContext(TableContext)
    const section = React.useContext(SectionContext)
    return (
      <tr
        ref={ref}
        role={role(stack, "row")}
        data-slot="table-row"
        className={cn(
          "transition-colors duration-100 motion-reduce:transition-none",
          stack &&
            section === "body" &&
            cn(
              // Title and value share the first line; the break after them sends the meta cells under it.
              "@max-lg:flex @max-lg:flex-wrap @max-lg:items-baseline @max-lg:gap-x-1.5 @max-lg:gap-y-[3px]",
              "@max-lg:after:order-3 @max-lg:after:basis-full @max-lg:after:content-['']",
              density === "compact" ? "@max-lg:py-2" : "@max-lg:py-[13px]",
              dividers === "rows" && "@max-lg:border-b"
            ),
          stack && section === "footer" && "@max-lg:flex @max-lg:items-baseline @max-lg:justify-between @max-lg:gap-3",
          className
        )}
        {...props}
      />
    )
  }
)
TableRow.displayName = "TableRow"

const stackClasses: Record<StackRole, string> = {
  title: "@max-lg:order-1 @max-lg:min-w-0 @max-lg:flex-1 @max-lg:pe-3 @max-lg:text-base @max-lg:font-medium",
  value: "@max-lg:order-2 @max-lg:text-right @max-lg:text-base @max-lg:tabular-nums",
  meta: "@max-lg:order-4 @max-lg:text-[13px] @max-lg:text-muted-foreground",
}

export interface TableHeadProps extends React.ThHTMLAttributes<HTMLTableCellElement> {
  /** Right-aligns the column's name over its figures. */
  numeric?: boolean
  /** Where a row's header goes when the table stacks, as on `TableCell`. Defaults to `title`. */
  stack?: StackRole
}

const TableHead = React.forwardRef<HTMLTableCellElement, TableHeadProps>(
  ({ className, numeric, scope, stack: place, ...props }, ref) => {
    const { stack, density, dividers } = React.useContext(TableContext)
    const section = React.useContext(SectionContext)
    return (
      <th
        ref={ref}
        scope={scope ?? (section === "header" ? "col" : "row")}
        role={role(stack, section === "header" ? "columnheader" : "rowheader")}
        data-slot="table-head"
        data-numeric={numeric || undefined}
        data-stack={stack && section === "body" ? (place ?? "title") : undefined}
        className={cn(
          "whitespace-nowrap px-3 text-left align-middle font-medium",
          section === "header" && "border-b text-xs text-muted-foreground",
          section === "body" && dividers === "rows" && "border-b",
          section === "header" && (density === "compact" ? "h-[34px]" : "h-10"),
          section === "body" && (density === "compact" ? "h-9" : "h-12"),
          section === "footer" && "h-9",
          numeric && "text-right tabular-nums",
          stack && section !== "header" && "@max-lg:block @max-lg:h-auto @max-lg:whitespace-normal @max-lg:border-0 @max-lg:p-0",
          stack && section === "body" && stackClasses[place ?? "title"],
          className
        )}
        {...props}
      />
    )
  }
)
TableHead.displayName = "TableHead"

export interface TableCellProps extends React.TdHTMLAttributes<HTMLTableCellElement> {
  /** Right-aligns the cell in tabular figures, so a column reads as one figure. */
  numeric?: boolean
  /**
   * Where the cell goes when the table stacks: `title` and `value` share the first line,
   * `meta` sits under them. Body cells without one are meta.
   */
  stack?: StackRole
}

const TableCell = React.forwardRef<HTMLTableCellElement, TableCellProps>(
  ({ className, numeric, stack: place, ...props }, ref) => {
    const { stack, density, dividers } = React.useContext(TableContext)
    const section = React.useContext(SectionContext)
    return (
      <td
        ref={ref}
        role={role(stack, "cell")}
        data-slot="table-cell"
        data-numeric={numeric || undefined}
        data-stack={stack && section === "body" ? (place ?? "meta") : undefined}
        className={cn(
          "whitespace-nowrap px-3 align-middle",
          section === "footer" ? "h-9" : cn(density === "compact" ? "h-9" : "h-12", dividers === "rows" && "border-b"),
          numeric && "text-right tabular-nums",
          stack && "@max-lg:block @max-lg:h-auto @max-lg:whitespace-normal @max-lg:border-0 @max-lg:p-0",
          stack && section === "body" && stackClasses[place ?? "meta"],
          className
        )}
        {...props}
      />
    )
  }
)
TableCell.displayName = "TableCell"

const TableCaption = React.forwardRef<HTMLTableCaptionElement, React.HTMLAttributes<HTMLTableCaptionElement>>(
  ({ className, ...props }, ref) => {
    const { stack } = React.useContext(TableContext)
    return (
      <caption
        ref={ref}
        data-slot="table-caption"
        className={cn("caption-top px-3 pb-3 text-left text-sm text-muted-foreground", stack && "@max-lg:block @max-lg:px-0", className)}
        {...props}
      />
    )
  }
)
TableCaption.displayName = "TableCaption"

export { Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption }
```
