Table

A table whose columns are data. It keeps scope on the headers, one source of truth for colSpan, and never hides row actions behind hover.

When to use it

The screen lists records that share one set of columns — by far the most common shape of an admin screen.
The columns are decided at runtime — by permission, plan or tenant settings. As data they are filtered by a single filter; as JSX it would be a condition in the header and in every row.
Rows carry actions (edit, delete). The table gives them a trailing column and leaves them visible instead of hiding them behind hover.

When not to use it

The data is not a grid. Label–value pairs for a single record are a description list, not a table; a screen reader would announce coordinates that lead nowhere.
The layout is a grid only visually (tiles, cards side by side). That is CSS grid — a <table> gives it meaning it does not have.
You need something from "what the first version cannot do" below and cannot wait for it. A conversion that would be a UX regression is a reason not to use the table — not a reason to work around it.

Properties

columns: readonly IngotColumn<Row>[] — Columns as data — adding one cannot break colSpan. Column properties are in the table below.
rows: readonly Row[] — The page of data currently being rendered.
rowKey: (row: Row) => string — Stable row identity.
empty: ReactNode — What to show instead of rows — typically IngotEmptyState.
loading: boolean — The table gets aria-busy and a single role=status row.
loadingLabel: string — Translated "Loading…". Required once loading can happen.
actions: (row: Row) => ReactNode — Row actions; adds a trailing column.
actionsLabel: string — Header of the actions column — for screen readers only.
caption: string — Table description for screen readers, rendered off-screen.
stickyHeader: boolean — Keeps the header visible inside a height-constrained scroll box.
density: "default" | "compact" — compact tightens cell padding to 8px — for screens where rows per screen matter.
sort: IngotSort — The current sort {key, dir}. The table never sorts — the order is whatever rows holds.
onSortChange: (sort: IngotSort) => void — Click on a sortable header: inactive → asc, asc ↔ desc.
selectedKeys: ReadonlySet<string> — Keys of the selected rows (rowKey). Together with onSelectedKeysChange it enables the checkbox column.
onSelectedKeysChange: (keys: ReadonlySet<string>) => void — The new set after every selection change — a row as well as select/clear all.
selectAllLabel: string — Translated label of the "select all" checkbox in the header.
selectRowLabel: (row: Row) => string — Translated label of a row checkbox ("Select {name}").
bulkbar: ReactNode — The bulk-action bar above the table; shown only while the selection is non-empty.
rowClassName: (row: Row) => string | undefined — Whole-row state (not selectable, highlighted), not per-cell styling.
className: string — Pass-through class on the table, typically min-w-[40rem].
rowTestId: (row: Row) => string — data-testid of a row — some screens' end-to-end tests hang off it.
testId: string — data-testid of the table.