Table

InstallCopy Anchor Link

pnpm exec vegastack-design verify table

pnpm dlx shadcn@4.21.0 add @vegastack/table

UsageCopy Anchor Link

import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@/components/ui/table";

<Table>
  <TableCaption>A list of your recent invoices.</TableCaption>
  <TableHeader>
    <TableRow>
      <TableHead className="w-[100px]">Invoice</TableHead>
      <TableHead>Status</TableHead>
      <TableHead>Method</TableHead>
      <TableHead className="text-right">Amount</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell className="font-medium">INV001</TableCell>
      <TableCell>Paid</TableCell>
      <TableCell>Credit Card</TableCell>
      <TableCell className="text-right">$250.00</TableCell>
    </TableRow>
  </TableBody>
</Table>;

Table wraps itself in its own data-slot="table-container" element — a relative w-full overflow-x-auto div — so a table that is wider than its column scrolls sideways without any wrapper at the call site.

AnatomyCopy Anchor Link

ExamplesCopy Anchor Link

CompositionCopy Anchor Link

The parts map one to one onto the HTML elements, so the tree is the markup: a caption, a thead of th, a tbody of td, and an optional tfoot.

Table
├── TableCaption
├── TableHeader
│   └── TableRow
│       ├── TableHead
│       ├── TableHead
│       ├── TableHead
│       └── TableHead
├── TableBody
│   ├── TableRow
│   │   ├── TableCell
│   │   ├── TableCell
│   │   ├── TableCell
│   │   └── TableCell
│   └── TableRow
│       ├── TableCell
│       ├── TableCell
│       ├── TableCell
│       └── TableCell
└── TableFooter

FooterCopy Anchor Link

Use the TableFooter component to add a footer to the table. It renders a tfoot, tints itself with bg-muted/50 and drops the last row's bottom border, so a totals row reads as a summary rather than as one more record.

ActionsCopy Anchor Link

A table showing actions for each row using a DropdownMenu. Give the trigger a sr-only label — an icon-only button in a repeated row is otherwise a column of unnamed buttons.

Data TableCopy Anchor Link

Table is the presentation layer; the row model is yours. Combine it with a row-model library such as @tanstack/react-table, or — as here — with ordinary React state, to get sorting, filtering and pagination. Nothing in this component holds row state, which is why the same parts serve both.

Put the sort control inside TableHead as a Button and mirror the direction onto the header's aria-sort, so the column announces its state rather than only drawing an arrow.

RTLCopy Anchor Link

Wrap the subtree in DirectionProvider direction="rtl". TableHead aligns with text-start and the checkbox padding rule uses pe-0, so the header and the cells flip with the reading direction; an explicit text-right on a numeric column stays where it is named.

API ReferenceCopy Anchor Link

Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell and TableCaption add no props of their own — each accepts everything its underlying element accepts (table, thead, tbody, tfoot, tr, th, td, caption), including colSpan, rowSpan, scope, aria-sort, className and ref.

AccessibilityCopy Anchor Link

• The parts render real table, thead, tbody, tfoot, tr, th, td and caption elements, so the browser's own table semantics — row and column position, header association, and the screen-reader table cursor — work with no ARIA at all.
• TableCaption is the table's accessible name. Every data table should have one, or an aria-label on Table when the name is already visible elsewhere on the page.
• A sortable column sets aria-sort on its TableHead (ascending, descending or none) and puts a real button inside it, so the control is reachable and its state is announced.
• Cells are whitespace-nowrap, so a wide table scrolls inside its own container rather than wrapping. Keep the container reachable from the keyboard when it scrolls — a scroll region with no focusable content needs a tab stop of its own.
• Selected rows take data-[state=selected] and a bg-muted fill. Selection is a colour change, so pair it with the checkbox or control that owns it rather than relying on the tint alone.

Do / Don'tCopy Anchor Link

DeviationsCopy Anchor Link

Upstream's file plus packages/ui/upstream/patches/table.patch. Every hunk:

• NO STYLING HUNK — every row this component could have argued with resolves as shadcn and therefore ships verbatim: LAY-6 (cells stay whitespace-nowrap, the head stays h-10 font-medium text-foreground with no wrap variable), COL-6 (the row hover is upstream's own hover:bg-muted/50) and COL-8 (a selected row is data-[state=selected]:bg-muted, not a pressed rung). The container is upstream's data-slot="table-container" div.
• DOC-2 — import { cn } from "cn" becomes @vegastack/design; our npm layer owns cn.
• DOC-1 — prettier reflow plus the registry-stamp.mjs provenance header the three-copy model needs; no decision of its own.