Table

Installation

$ npx shadcn@latest add https://goodui.dev/r/table.json

The file lands in components/goodui/table.tsx and is yours to edit. With the @goodui registry added, npx shadcn@latest add @goodui/table works too.

Usage

import { Table, type TableColumn } from "@/components/goodui/table"

type Invoice = { id: string; client: string; due: string; amount: number; status: "paid" | "overdue" }

const columns: TableColumn<Invoice>[] = [
  { key: "id", header: "Invoice", primary: true },
  { key: "client", header: "Client", sortable: true },
  { key: "due", header: "Due" },
  {
    key: "amount",
    header: "Amount",
    numeric: true,
    sortable: true,
    render: (r) => r.amount.toLocaleString("en-US", { style: "currency", currency: "USD" }),
  },
]

export function Invoices({ invoices }: { invoices: Invoice[] }) {
  return (
    <Table
      aria-label="Invoices"
      columns={columns}
      data={invoices}
      rowTone={(r) => (r.status === "overdue" ? "danger" : "none")}
      stack="md"
      caption="October invoices"
    />
  )
}

When to use

Examples

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

<Table variant="striped" density="compact" aria-label="Schedule">
  <TableHeader>
    <TableRow>
      <TableHead>Time</TableHead>
      <TableHead>Client</TableHead>
      <TableHead numeric>Price</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow tone="info">
      <TableCell label="Time">09:30</TableCell>
      <TableCell label="Client">Omar D.</TableCell>
      <TableCell label="Price" numeric>$40</TableCell>
    </TableRow>
  </TableBody>
</Table>

const [sort, setSort] = React.useState<TableSort | null>({ key: "rating", direction: "desc" })
const rows = React.useMemo(() => sortTeam(team, sort), [team, sort])

<Table columns={columns} data={rows} sort={sort} onSortChange={setSort} variant="cards" hover="lift" />

<Table
  columns={columns}
  data={team}
  selectedKeys={picked}
  onRowClick={(r) => togglePicked(r.id)}
  aria-label="Team"
/>

API reference

Accessibility

• •It renders a real <table> with <th scope="col">, so screen readers announce headers with each cell. Pass aria-label or a caption to name it.
• •Sortable headers are <button>s inside the <th>; the <th> gets aria-sort (ascending or descending) and the button reads ", sorted ascending" (labels.sortedAscending / sortedDescending).
• •Selected rows get aria-selected. Row tones are color plus a start-edge bar; also show the state as text (a badge) so it does not rely on color alone.
• •When stack is set, explicit table, rowgroup, row, columnheader and cell roles are added, because display:block can drop table semantics in some browsers. Stacked cells show their column label from data-label (columns: label or header text; parts: the label prop).
• •Loading shows skeleton rows with a visually hidden "Loading" (labels.loading) and aria-busy on the body; the empty state text comes from empty or labels.empty.
• •When the table can scroll (maxHeight, or wider than its container), the scroll box becomes a focusable role="region" named by the caption, the table's aria-label or labels.scrollRegion, so keyboard users can scroll it.

Motion

• •fade: body rows fade in over 350 ms on mount. stagger: rows rise 6px and fade in over 400 ms, 35 ms apart, capped at the 13th row (455 ms). Remount (change key) to replay.
• •hover lift moves the row up 1px over 180 ms; tint and accent change the background; the sort arrow turns 180° in 200 ms between ascending and descending.
• •Reduced motion: entrances, transitions and the lift are off, and the skeleton shimmer stops.

• •Pure CSS for every layer (one shared <style> tag). The only measurement is one ResizeObserver that checks horizontal overflow to make the scroll box focusable. Sorting with columns + data is a stable in-memory sort with Intl.Collator (numeric, case-insensitive).
• •It renders every row. For hundreds of rows or more, use data-grid, which virtualizes.

Notes for AI

Coding agents read these rules through MCP and llms.txt, or paste this page with Copy page.

FAQ

Related