A headless table for the toolkit

The principle

The toolkit handles presentation. Teams handle logic.

The table package is headless by design — it controls how the table looks; everything else stays outside the toolkit. Teams bring their own logic using whichever fits their stack — plain useState, TanStack Table, React Aria, or anything else.

This keeps the bundle small, avoids locking teams into a specific data or state library, and lets the same primitives cover a wide range of table designs without forcing one product’s logic onto another’s UI.

Quick start

import { Table } from "@toolkit/table";

<Table>
  <Table.Header>
    <Table.Row>
      <Table.Head>Name</Table.Head>
      <Table.Head width={140}>Status</Table.Head>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    {rows.map((row, i) => (
      <Table.Row key={row.id} hideDivider={i === rows.length - 1}>
        <Table.Cell>{row.name}</Table.Cell>
        <Table.Cell width={140}>{row.status}</Table.Cell>
      </Table.Row>
    ))}
  </Table.Body>
</Table>

Plain useState example

const [dir, setDir] = useState<"ascending" | "descending" | "none">("none");
const sorted = useMemo(() => sortBy(rows, "name", dir), [rows, dir]);

<Table.Head sort={dir} onSortToggle={() => setDir(next(dir))}>
  Name
</Table.Head>

TanStack Table example

const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  getSortedRowModel: getSortedRowModel(),
});

table.getHeaderGroups().map((hg) => (
  <Table.Row key={hg.id}>
    {hg.headers.map((h) => (
      <Table.Head
        key={h.id}
        sort={h.column.getIsSorted() || "none"}
        onSortToggle={h.column.getToggleSortingHandler()}
      >
        {flexRender(h.column.columnDef.header, h.getContext())}
      </Table.Head>
    ))}
  </Table.Row>
));

Design rationale

1. Headless — state lives outside

Every stateful prop is fully controlled by the consumer.

2. What's not in the toolkit

3. Stable height across pages (Table.Body minRows)

Paginated tables have three states that naturally render at different heights:

1. Full pages — pageSize rows, divider stack between them
2. Partial last page — fewer than pageSize rows
3. No-results state — a single empty-state block

Pass minRows={pageSize} to <Table.Body> and the body locks itself to the full page height for all three:

<Table.Body minRows={pageSize}>
  {rows.length === 0 ? (
    <Box style={{ flex: 1 /* centered no-results message */ }}>
      No results
    </Box>
  ) : (
    rows.map((row, i) => (
      <Table.Row key={row.id} hideDivider={i === rows.length - 1}>
        {/* cells */}
      </Table.Row>
    ))
  )}
</Table.Body>

Behavior:

• Body reserves a min-height of minRows × rowHeight + (minRows - 1) × dividerHeight.
• When all children are Table.Row and there are fewer than minRows, invisible placeholder slots are appended.
• When the body holds a non-row child (e.g. an empty-state panel), no placeholders are appended — only min-height is enforced, so the panel can stretch via flex: 1.

API reference

Components

Toolkit-specific props