# Table

> A semantic data table with right-aligned tabular numbers, selection and contained horizontal scroll.

Category: Data display · Atomic level: molecule
Page: https://ui.dtheo.dev/docs/components/table

## Install

```bash
npx dtheo@latest add table
# or, with the shadcn CLI
npx shadcn@latest add https://ui.dtheo.dev/r/table.json
```

Dependencies: clsx, tailwind-merge. Registry dependencies: utils.

## Exports

`Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`, `TableCell`, `TableCaption`, `useRowSelection`, `withShift`

## Use it for

- Run history, measurements, any rows people compare
- Selecting rows to act on: `useRowSelection` adds Shift-click ranges, like a mail inbox

## Reach for something else

- Layout: use grid or flex
- A single record: use a description list

## Keyboard

| Keys | Action |
| --- | --- |
| Space | Select or clear the focused row |
| Shift + Space / Shift + click | Select every row between the last one and this one |

## Accessibility

- Uses native table semantics; no ARIA grid unless cells are interactive.
- Selected rows set `aria-selected`; every row checkbox is named after its row.

## Examples

### table

```tsx
import { CircleCheckIcon, CircleXIcon, TriangleAlertIcon } from 'lucide-react';
import { Badge } from '@/components/ui/badge';
import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from '@/components/ui/table';

type Result = 'fail' | 'warn' | 'pass';

const runs: Array<{
  id: string;
  profile: string;
  result: Result;
  kp: number;
  overshoot: number;
  settling: number;
  peak: number;
}> = [
  {
    id: 'R-0412',
    profile: 'High-gain step',
    result: 'fail',
    kp: 4.2,
    overshoot: 17.6,
    settling: 186,
    peak: 9.41,
  },
  {
    id: 'R-0411',
    profile: 'High-gain step',
    result: 'fail',
    kp: 3.9,
    overshoot: 11.2,
    settling: 174,
    peak: 8.9,
  },
  { id: 'R-0410', profile: 'Fast rise', result: 'warn', kp: 3.6, overshoot: 7.9, settling: 192, peak: 8.63 },
  {
    id: 'R-0409',
    profile: 'Nominal step',
    result: 'pass',
    kp: 3.2,
    overshoot: 3.8,
    settling: 158,
    peak: 8.3,
  },
  {
    id: 'R-0408',
    profile: 'Nominal step',
    result: 'pass',
    kp: 3.2,
    overshoot: 6.8,
    settling: 161,
    peak: 8.54,
  },
  {
    id: 'R-0407',
    profile: 'Damped step',
    result: 'pass',
    kp: 2.8,
    overshoot: 5.2,
    settling: 149,
    peak: 8.42,
  },
];

const resultBadge = {
  fail: { variant: 'destructive', Icon: CircleXIcon, word: 'Failed' },
  warn: { variant: 'warning', Icon: TriangleAlertIcon, word: 'Near limit' },
  pass: { variant: 'success', Icon: CircleCheckIcon, word: 'Passed' },
} as const;

export default function TableExample() {
  const selected = 'R-0412';
  return (
    <div className="w-full overflow-hidden rounded-card border border-border bg-card">
      <Table>
        {/* Left-aligned: on narrow screens the table scrolls and a centered caption would be cut off. */}
        <TableCaption>Bench 3, firmware 4.18.2. Selected: R-0412.</TableCaption>
        <TableHeader>
          <TableRow className="hover:bg-transparent">
            <TableHead>Run</TableHead>
            <TableHead>Profile</TableHead>
            <TableHead>Result</TableHead>
            <TableHead numeric>Kp</TableHead>
            <TableHead numeric>Overshoot (%)</TableHead>
            <TableHead numeric>Settling (ms)</TableHead>
            <TableHead numeric>Peak torque (N·m)</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {runs.map((run) => {
            const badge = resultBadge[run.result];
            return (
              <TableRow key={run.id} aria-selected={run.id === selected}>
                <TableCell className="font-medium tabular-nums">{run.id}</TableCell>
                <TableCell className="text-muted-foreground">{run.profile}</TableCell>
                <TableCell>
                  <Badge variant={badge.variant}>
                    <badge.Icon aria-hidden="true" />
                    {badge.word}
                  </Badge>
                </TableCell>
                <TableCell numeric>{run.kp.toFixed(2)}</TableCell>
                <TableCell numeric>{run.overshoot.toFixed(1)}</TableCell>
                <TableCell numeric>{run.settling}</TableCell>
                <TableCell numeric>{run.peak.toFixed(2)}</TableCell>
              </TableRow>
            );
          })}
        </TableBody>
      </Table>
    </div>
  );
}
```

### table-selection

```tsx
import { Button } from '@/components/ui/button';
import { Checkbox } from '@/components/ui/checkbox';
import { Kbd } from '@/components/ui/kbd';
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/components/ui/table';
import { useRowSelection, withShift } from '@/components/ui/use-row-selection';

const runs = [
  { id: 'R-0412', profile: 'High-gain step', overshoot: 17.6 },
  { id: 'R-0411', profile: 'High-gain step', overshoot: 21.3 },
  { id: 'R-0410', profile: 'Fast rise', overshoot: 9.4 },
  { id: 'R-0409', profile: 'Nominal step', overshoot: 4.1 },
  { id: 'R-0408', profile: 'Nominal step', overshoot: 6.8 },
  { id: 'R-0407', profile: 'Damped step', overshoot: 3.2 },
];
const ids = runs.map((r) => r.id);

export default function TableSelectionExample() {
  const sel = useRowSelection(ids);
  return (
    <div className="flex w-full max-w-lg flex-col gap-2">
      <div className="flex h-7 items-center justify-between gap-3 text-label font-normal text-muted-foreground">
        {sel.count ? (
          <>
            <span className="tabular-nums">{sel.count} selected</span>
            <Button size="xs" variant="ghost" onClick={sel.clear}>
              Clear
            </Button>
          </>
        ) : (
          <span className="flex items-center gap-1.5">
            Click one, then <Kbd>⇧</Kbd> click another
          </span>
        )}
      </div>
      <div className="overflow-hidden rounded-card border border-border bg-card">
        <Table>
          <TableHeader>
            <TableRow className="hover:bg-transparent">
              <TableHead className="w-10">
                <Checkbox
                  aria-label="Select all runs"
                  checked={sel.all}
                  indeterminate={sel.some}
                  onCheckedChange={(c) => sel.setAll(ids, c)}
                />
              </TableHead>
              <TableHead>Run</TableHead>
              <TableHead>Profile</TableHead>
              <TableHead numeric>Overshoot</TableHead>
            </TableRow>
          </TableHeader>
          <TableBody>
            {runs.map((r) => (
              <TableRow key={r.id} aria-selected={sel.isSelected(r.id) || undefined}>
                <TableCell>
                  <Checkbox
                    aria-label={`Select ${r.id}`}
                    checked={sel.isSelected(r.id)}
                    onCheckedChange={(c, d) => sel.toggle(r.id, c, withShift(d))}
                  />
                </TableCell>
                <TableCell className="font-mono text-label">{r.id}</TableCell>
                <TableCell>{r.profile}</TableCell>
                <TableCell numeric>{r.overshoot.toFixed(1)} %</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </Table>
      </div>
    </div>
  );
}
```

## Used in

- Run review (page): https://ui.dtheo.dev/examples/run-review
- Motor map (page): https://ui.dtheo.dev/examples/motor-map
- Lab assistant (page): https://ui.dtheo.dev/examples/assistant
- Data table pattern (template): https://ui.dtheo.dev/docs/patterns/data-table
