DataTable

Array of row objects

Column definitions

Enable row selection

Selection toolbar actions

Per-row actions column. Mark an action `inline: true` (with an icon) to render it as an icon button with its label as tooltip (visible by default — see `rowActionsReveal`); the rest collect in a "⋯" overflow menu. `tone: 'danger'` for destructive styling, `disabled` grays out without hiding. Keep 2–3 inline, long tail in the menu.

When the row-action icons show. 'always' (default) keeps them on screen — most discoverable, and the only option that works on touch. 'hover' reveals them on row hover / keyboard focus / open menu (denser Linear/Attio pattern, but invisible on touch).

Saved view presets

Top-level UI state

Row click handler

Show a Filters button in the toolbar that toggles a left-hand filter panel, wired to the same column filters as the header popovers. Off by default. PREREQUISITE: the panel lists one control per column that declares `meta.filterType` ('text'|'number'|'date'|'enum'|'boolean') AND has a resolvable value (an accessorKey/accessorFn or matching id) — columns without a filterType are skipped, so enabling the prop on a table whose columns declare none renders an empty panel. Give each filterable column a meta.filterType.

Placement of the filter panel (needs enableFilterPanel). 'rail' (default) is an inline sibling that takes 256px when open — best for a full-width table. 'overlay' floats the panel over the table's left edge with a dismiss backdrop so the table keeps its full width — use inside Sheets/drawers/narrow panes where a rail would crush the columns. 'auto' is rail on wide containers, overlay once the container narrows (<560px). Default 'rail' is byte-identical. MCP feedback fb_903212e0.

Let the user drag the filter panel's right edge to resize it. On by default — the handle is a transparent 6px strip that only paints on hover/focus, and the panel still opens at defaultFilterPanelWidth, so nothing moves until it is dragged. Keyboard-resizable too: the handle is a focusable ARIA separator (arrows nudge 8px, Shift+arrow 32px, Home/End snap to the bounds). Set false for a fixed-width panel.

Width (px) the filter panel opens at. Default 256 — the previous fixed width, so an untouched panel is unchanged.

Controlled filter-panel width (px). Pass with onFilterPanelWidthChange to own the width — e.g. to persist it per user. Clamped to filterPanelMinWidth/filterPanelMaxWidth on read, so a stored value can never render the panel out of bounds.

Fires on every resize step with the new clamped width (px). Use with filterPanelWidth for a controlled panel, or alone to persist an uncontrolled one.

Lower resize bound (px). Default 200 — below this the enum option rows wrap badly.

Upper resize bound: px (default 560 — above this the panel crowds out the table it filters), or a CSS length such as '60vw', '70%' (of the panel+table row) or '40rem', which is resolved in the browser and re-resolved as the screen resizes — a screen-relative ceiling suits long (e.g. Thai) filter labels better than a fixed px. Until it is resolved (SSR, first paint) the 560px default applies, and it never resolves below filterPanelMinWidth. MCP feedback fb_222f783b.

Renders a "?" beside the column header explaining what the column means. A node gives a one-liner; { title, body } gives a heading plus detail. Composing this yourself needs a function `header`, which loses the plain-string header ergonomics (filter chips, the column picker and export all read `label`) and repeats on every column. The trigger is deliberately a SIBLING of the sort control, never a child: a button inside the sort button is invalid HTML and a React 19 SSR hydration error. On a column that opts in, the sort hit area shrinks from the whole header cell to the label. MCP feedback fb_54569a6f.

Lower width bound (px) for this column, enforced on drag and on keyboard resize. DEFAULT: derived from the column's own NAME (its label plus the affordances that header renders — sort chevron, "?" help, drag handle), clamped to [60, 220]. It used to be a flat 60px, which is narrower than almost any real column name, so the default state of a resizable column was "your header is unreadable". Thai tone marks and vowel signs are not counted, since they advance the pen by zero. Set this to take the floor back under your own control. MCP feedback fb_f26eab7f.

localStorage key that persists the UNCONTROLLED panel width across sessions. Ignored when filterPanelWidth is controlled. The stored value is adopted after mount (never during render), so it cannot cause a hydration mismatch. Best-effort — a storage failure in private mode is swallowed. MCP feedback fb_c860aaf0.

Whether the filter panel starts open. Default false (unchanged).

Controlled filter-panel open state. Pass with onFilterPanelOpenChange to own it — e.g. to restore whether the user left the panel open on their last visit. MCP feedback fb_4c48a1f5.

Fires whenever the panel opens or closes — the toolbar button, the panel close button, or the overlay dismiss backdrop. Use with filterPanelOpen for a controlled panel, or alone to persist an uncontrolled one.

Show a toolbar toggle that expands ONLY the table box to the viewport width and back (grid and pivot). Off by default. A momentary "let me see this" gesture, not a layout preference: the state is never stored and never reaches the preference callbacks, so a host that persists every preference can never restore a table expanded. Nothing else on the page moves — the table grows past its container towards the viewport's far edge, so the heading and the KPI cards above it stay put. Width: calc(100vw - var(--b69-table-inset) - var(--b69-table-gutter)). The component MEASURES --b69-table-inset (the gap between the viewport's leading edge and the table's own, i.e. your sidebar plus page padding) and seeds it, so this needs no app CSS; set it on any ancestor to pin an exact value, and --b69-table-gutter (default 1.5rem) for the far-edge breathing space. The root reports data-expanded="yes"/"no". Requirement: no ancestor may clip horizontally, or the extra width is cut off. MCP feedback fb_f26eab7f.

Controlled expanded state. Pass with onFullWidthChange to drive the expansion from a button of your own; omit both and the built-in toggle owns it. Uncontrolled seed: defaultFullWidth.

Whether the uncontrolled table starts expanded. Default false.

Fires whenever the table expands or collapses. Deliberately NOT one of the persisted preference callbacks — the expansion is a gesture, so storing it is the one thing this prop is not for.

Drag-and-drop column reorder

Controlled column visibility ({ [columnId]: boolean }, false = hidden). Pass with onColumnVisibilityChange to own it; omit both and the table keeps the state internally, seeded by initialColumnVisibility.

Fires whenever a column is shown or hidden — the built-in Columns menu, its Reset entry, the toolbar Reset, or a saved view being applied. This is what lets an app persist a user's hidden columns instead of shipping a second column menu of its own (fb_de40b58f).

Controlled column pinning. The table re-adds its own system columns (selection, expand, row actions) to the edges on read, so a stored value that only lists the caller's columns can never unpin them.

Fires whenever a column is pinned or unpinned — the header pin menu, the header right-click cycle, or a view being applied.

Controlled column order. Unknown ids are dropped and unmentioned columns keep their declared position, so a stored order survives a column being added or removed. Replaces the remount-with-a-key workaround an initialColumnOrder-only API forced.

Controlled per-column widths in px, keyed by column id (what the resize handles write). Uncontrolled seed: initialColumnSizing.

Fires when a column is resized by drag or keyboard, with the full sizing map.

Controlled sorting (uncontrolled seed: initialSorting).

Fires on header click / shift-click multi-sort / a view being applied.

Controlled grouping (uncontrolled seed: initialGrouping).

Fires when the Group-by menu or a header Group-by entry changes the grouped columns.

Controlled column filters (uncontrolled seed: initialColumnFilters).

Fires for every filter route — header popover, filter panel, clearing a chip, Clear filters.

Filters the table starts with.

Column widths (px) the table starts with — e.g. the widths this user dragged last time.

Value the toolbar search box starts with.

Fires on every keystroke in the toolbar search box (the raw value; filtering stays debounced 200ms inside). Callback-only — a controlled search box would round-trip every keystroke through the host.

Fires when the page or the page size changes, including the automatic snap back to page 1 when the filtered row set changes. Callback-only; seed the size with initialPageSize.

Fires when rows expand or collapse — a group chevron, Expand all / Collapse all, a detail row. masterDetail.onExpandedChange reports the same event as row ids. Callback-only: master/detail exclusive mode owns this state's shape.

Fires when a saved view is applied or saved (the view) or cleared by Reset (null).

Cell range selection + copy TSV

Pin rows to top / bottom

Excel export action (uses meta.excelFormat)

Alternate row background (zebra striping); frozen columns stripe too

Separator display (default 'horizontal' = row dividers only)

Column width strategy. 'fit' fills the container — flexible columns (no explicit size, unpinned, not user-resized) share the remaining width so the table never overflows or clips a trailing column; explicit-size / system / pinned columns keep their widths (table-layout: fixed makes the <colgroup> authoritative). 'auto' (default) lets the table scroll when columns exceed the viewport, and there an explicit `size` is a guaranteed MINIMUM: it is emitted as a min-width on the cells, because in table-layout: auto a <col width> is only a hint the browser drops once the table is over-constrained — a 220px column measured 130px (fb_c5ab85e3). Columns with no `size` stay fully fluid in 'auto'. With no flexible column present 'fit' falls back to 'auto', floors included, so the two agree.

Show a toolbar CSV Import button

Receives parsed CSV records (keyed by header) on import

Excel-style mode: row-number gutter (a system column: no lock, pin menu, drag or resize handle), active-cell keyboard nav, type-to-edit/F2, fill handle, paste-to-fill (implies cell selection; editing needs editable columns)

Batched change callback for spreadsheet fill/paste/edits (falls back to onCellEdit per cell)

Render expandable detail content per row

Shown when active filters/search reduce a NON-empty dataset to zero rows (defaults to a "no matching rows" message). Distinct from emptyState — which is only shown when the dataset is genuinely empty — so a "create your first record" prompt never renders on a filtered-to-zero table.

Render a spreadsheet-style pivot matrix from the data (multi-level column headers + row / column / grand totals + Excel export)

Show the saved-views control in the toolbar. Default true, which is what it always did — it was the one toolbar control with no switch, so a table with no views still offered the button (fb_438fd0e6).

The rows arrive already ordered and a header click asks the SERVER for a different order. Pair with `sorting` + `onSortingChange`: the header keeps its affordance and its arrow, and the client-side sorter is not applied, so a page of server-sorted rows is no longer re-sorted among itself (fb_438fd0e6).

How many rows exist on the SERVER when this table holds one page. Without it the footer counts rows in the browser — 30 of 120 read "Showing 1–30 of 30". It also drives the page count, so the pager reaches every page rather than stopping at the end of the current fetch (fb_438fd0e6, fb_8e084154).

Override any built-in UI string — toolbar (search placeholder, density, Columns/Views/Group, Export), pagination ('Showing {range} of {total}', '{count} / page', '{page} / {pageCount}', the page-size select's accessible name), selection ('{count} selected', select-all/select-row aria), empty/error states, filter-panel controls (operator options and the match-type select's accessible name, value/min/max placeholders, option search, boolean Either/Yes/No, date-range prompt), row-actions and sort/pin/resize aria-labels, and the Ctrl/Cmd+C cell-copy toasts ('Copied {count} cells to clipboard' / 'Copy failed' + its hint). Strings with {token} placeholders are templates. Defaults: DEFAULT_DATA_TABLE_LABELS (English, exported). Wrap the app in LocaleProvider to also format all counts per locale (e.g. Thai numerals).