Data Grid

Install

pnpm exec vegastack-design verify data-grid

pnpm dlx shadcn@4.21.0 add @vegastack/data-grid

Usage

Virtualized keyboard navigation scrolls an offscreen target into view and transfers focus when its cell mounts.

import { DataGrid } from "@/components/ui/data-grid";

<DataGrid
  aria-label="Deals"
  columns={[
    { key: "name", header: "Name", sortable: true, mobile: "visible" },
    {
      key: "stage",
      header: "Stage",
      editable: { type: "select", options: stages },
    },
    {
      key: "amount",
      header: "Amount",
      align: "end",
      mobile: "merge",
      render: (d) => <span className="tabular-nums">{d.amount}</span>,
    },
  ]}
  data={deals}
  getRowId={(d) => d.id}
  onCellCommit={(row, key, value) => api.patch(row.id, { [key]: value })}
  selectable
/>;

DataGrid is the commissioned full-parity sibling DataList always pointed to. The sorted row model comes from TanStack Table (the sanctioned engine); row and column windowing from TanStack Virtual behind the virtualize and virtualizeColumns flags; the APG grid keyboard layer — which no library ships — is the component's own.

// Spreadsheet scale: the host sorts and groups on the server; both axes are windowed.
<DataGrid
  aria-label="Sample requests"
  columns={fields} // { key, header, width, frozen, headerMenu, summaryOptions, … }
  data={rows}
  getRowId={(row) => row.id}
  sortMode="manual"
  sort={sort}
  onSortChange={setSort}
  onColumnResize={saveWidth}
  onColumnReorder={saveOrder}
  columnOrder={order}
  virtualize
  virtualizeColumns
  rowHeight="short"
  maxHeight="70dvh"
  ariaRowCount={total + 1}
  headerTrailing={(focus) => <AddFieldButton {...focus} />}
  summaryRow={{
    label: `${total} rows`,
    value: fns,
    onValueChange: setFn,
    results,
  }}
  cellMenu={(rowId, key) => <CellMenuItems rowId={rowId} field={key} />}
/>

Two deliberate differences from DataList, for migrators:

1. Cells render as component elements, so a render implementation may use hooks (DataList invokes render as a plain function and cannot allow that).
2. The grid sorts its own data — that is what the row-model engine is for. sort/onSortChange stay controllable for URL state. Pass sort without onSortChange when a toolbar owns the sort: headers stop being sort buttons, and each sorted column shows a read-only ↑/↓ (with its ordinal in a multi-sort) and aria-sort.

Scope

Reversed in 0.25.69 (Regent Tables, R2): the grid used to leave out column resize, a reorder affordance, aggregation footers, and grouped virtualization. It now hosts a 50,000-row, 150-column, server-sorted grid — so frozen and resizable columns, header drag-to-reorder, a summary row, host-sorted rows, host groups and column windowing are in. It still computes nothing the host should: summary values, server sort orders and group pages come in as props.

Two layouts

The grid renders its own <table> inside ONE scroll viewport (data-slot="grid-viewport"), so the sticky header, the sticky summary row and the frozen columns all resolve against the same box.

The fixed layout fills its box: the table is never narrower than the viewport, and a last, unsized filler track takes whatever the columns leave. The header band, the row borders and washes, the summary row and the footer reach the viewport's end while every column keeps its own width, and the headerTrailing "+" column stays right after the last real column.

On a phone-width container (under 40rem) phoneLayout="cards" shows each row as a card: the primary value as its title (it opens the row, with onRowOpen) and the next cardFields columns (3 by default) as labelled values. The grid decides by its own width, so a tablet keeps the grid and a narrow pane gets cards. A grid with a summaryRow shows it above the cards as one read-only line — its label ("412 rows"), then "Amount · Sum 12,400" for each summarised column — wrapping on a narrow screen; the functions are chosen from the table's footer.

The toolbar

The toolbar row holds the host's toolbar slot on the leading edge and the grid's own controls on the trailing edge: the hidden-columns hint, then the "Columns" picker.

The picker is on by default and turns off with columnPicker={false} — a fixed three-column grid should not carry a column manager, and a host that drives visibility from its own settings surface already has one. With no toolbar, no picker and nothing hidden, the toolbar row is not rendered at all.

Examples

Opening rows

A grid row opens its record — a peek beside the grid — without fighting cell selection or editing. onRowOpen(rowId, { event, index }) adds an Open button (24×24) at the start of each row's primary cell: it shows on row hover and on keyboard focus anywhere in the row (always on touch) and holds its place at rest, so nothing shifts. From the keyboard, Space on any of the row's cells or Enter on its primary cell (the row header) opens it;

F2 or typing still edits. activeRowId marks the open row (data-peek-active, the accent wash) and scrolls it into view as the peek walks; actionsRef exposes getRowOrder() for that walk and focusCell(rowId, key) to put the active cell on a new row.

The active cell is outlined (2px, inset) while the grid holds focus, whether a click or a key put it there; a range's other cells take the tint. A header with a headerMenu is one button that opens the menu (sort lives in it), a column's icon sits before its label, and a numeric column lines its figures and its header up at the end. selectionActions docks the same selection bar as DataList's while rows are checked. Narrow the preview below 40rem to see the cards.

Embedded in a page

embedded makes the grid a table block inside a page or document: one framed block with the toolbar (a BlockHeader) on top and the footer under the rows. Its height comes from its rows — at most maxRows (25 by default) — so it never scrolls inside itself; it scrolls sideways when its columns overflow, with no cap on how many show. While more columns sit past the end, a quiet edge shade marks the trailing side (any grid that overflows sideways shows it), and a sideways pan stops at the grid's edge instead of moving the page. The built-in column picker is off (the block header's View menu owns the fields). Rows open exactly as they do on a table page (onRowOpen), and cells edit in place.

footer takes an object for a block: { onNewRow, shown, total } puts + New row at the start and "25 of 117" at the end (only while rows are left out). readOnly is for people who can see the table but not change it: no cell editors, paste, clear, fill or undo keys, no add-field column and no + New row — rows still open, sort and select. Turn Can edit off in the preview.

Empty state

An empty grid wider than its box holds its empty (or error) state to the viewport — centred where the reader is, never clipped by the columns scrolled out of view. loading draws loadingRows skeleton rows (5 by default): pass the rows the page will hold so the loaded grid lands without a shift.

Grouping

One group column groups the rows by value on the client. Groups are flattened into the one row list: a group header is a row of its own, followed by its rows, so grouping and virtualize combine. The group header is the shared SectionToggle DataList's sections use: the row count sits after the label in muted tabular numerals (no parentheses), and a screen reader hears it as "Open, 2 rows". The header rows are on the keyboard path: ↑/↓ stop on them and

Enter or Space toggles.

Spreadsheet scale

150 columns × 50,000 rows: a frozen primary column, resizable columns (drag the edge, double-click to fit, or Alt+←/→ on a focused header), both axes windowed, fixed short rows, and a sticky summary row whose values the host computes. The grid renders the frozen cells, two spacer cells and the columns in view — never 150 cells a row.

For the 8 ms scroll budget the structure is fixed: one scroll box, fixed row heights, memoised rows and cells. Keep columns and cellStatus stable (useMemo, useCallback) and give a changed row a new object — a cell re-renders only when its row object or its column definition changes.

Host groups

sections hands the grid the server's groups: each names its rows (rowIds), its total count, and its own loadMore, so every expanded group pages its own keyset. The grid flattens them into the one virtual list — group header, the group's loaded rows, then the group's load-more row while it has more.

Paged mode

pagedMode turns row windowing off and puts a CursorPager (Previous / Next, no page numbers) under the grid, for people who page instead of scroll. Column windowing stays on. ariaRowIndexOffset keeps the row numbers true across pages.

Cells mode

selectionMode="cells" makes the grid a spreadsheet surface. A range is kept by row id and column key (use-grid-selection), so it survives a refetch and windowing; it covers loaded rows only.

• Select: Shift+arrows, Shift+click or a drag extend the range; Shift+Space takes the row, Ctrl+ Space the column, ⌘/Ctrl+A everything; a plain move or Escape collapses it. A range of more than one cell is announced ("4 by 3 cells selected").
• Copy, cut, paste go through the copy, cut and paste events (never the async Clipboard API) as TSV plus a bare HTML table, read by grid-clipboard: Excel, Google Sheets (with its exact numbers), Numbers and Airtable. One pasted value fills the range; a pattern that divides it tiles. Each column's parse(cell, row) turns a pasted cell into its value and format(row) writes its copy text. A column with neither parse nor editable is read-only to paste, clear and fill. Rows that run past the last loaded row go to onPasteOverflow — the host asks "Add 38 rows?". A paste into an open editor is the editor's.
• Write: a paste, a clear (Delete) or a cut is ONE onCellsCommit(changes) batch; the host answers per cell (ok, conflict, invalid, stale_schema) and the grid announces "Pasted 120 cells · 4 skipped".
• Fill: drag the handle on the range's corner up or down, or ⌘/Ctrl+D to fill down; onFill({ source, target, series }) — Alt while dragging asks for a series. The host computes the values.
• Undo ⌘/Ctrl+Z and redo ⇧⌘Z / Ctrl+Y reach onUndo / onRedo; the host owns the history.
• Someone else's change: remoteChanges (keyed by gridCellKey(rowId, key)) pulses the cell with the system's highlight-on-change ring (motion-flash, gone under reduced motion) and shows the author in its corner for 1.5s; only the focused cell's announcement is spoken.

Inline editing

Editable columns open EditableCell in focusMode="managed" — the grid owns reachability, the cell owns the editor and its async status. Enter/F2 edits keeping the value; typing a character edits replacing it (text and number editors); Enter commits and moves down, Tab/Shift+Tab commit and move across; Escape restores grid navigation; a rejected commit reverts and announces. While an IME is composing, no key commits or moves.

An editable column's render is its display while the cell holds a non-empty value and is not being edited (tags, chips, avatars); an empty cell is blank — the editor's placeholder shows only once it edits — and a pending commit shows its value as text until the host's updated row arrives. Without a render the editor's own display shows (a select's label, a formatted date or number). A custom editor's render receives the row with value, seed, commit and cancel, so it can read the typed value the cell's string can't carry: seed is the key that opened it (type-to-edit), and commit(next, move) with "down", "up", "right" or "left" steps the grid on the way Enter and Tab do.

Floating editors

editing="floating" opens a custom editor over its cell instead of inside it: the cell keeps drawing its resting face, and the editor — anchored at the cell, reaching 2px past it, at least as tall as the cell — floats on a FloatingCellEditor with the page locked behind it. The column's editable.floating sets the editor's size (text-like types text, dates wide, pickers picker) and dismissOnPress, for an editor that saves when something is chosen and so needs a press outside to close it. The built-in text, number, date and select editors stay inline.

<DataGrid
  editing="floating"
  columns={[
    {
      id: "notes",
      editable: {
        type: "custom",
        floating: { size: "text" },
        render: ({ value, commit, cancel }) => (
          <FieldCellEditor
            variant="cell"
            type="text"
            label="Notes"
            value={value}
            onCommit={commit}
            onCancel={cancel}
          />
        ),
      },
    },
  ]}
/>

Filling the page

fill makes the viewport as tall as the room from its top edge to the bottom of its nearest scrolling ancestor, so the grid's scroll bar rests at the bottom of the window even when the rows are few; it follows the window and anything above the grid that comes, goes or resizes, and is never under 240px. A maxHeight of its own wins. Inside an AppShellPage, wrap the grid in AppShellBleed so it reaches the page's side edges and bottom. endSpacer leaves a band (180px, or the pixels given) after the last row so the last rows scroll clear of anything floating at the bottom, columnDividers rules every column's end (the frozen columns too, drawn over their sticky background) and editingTint fills the cell being edited with the accent tint.

<AppShellPage size="full">
  <PageHeader title="Schedule" />
  <AppShellBleed>
    <DataGrid fill endSpacer columnDividers editingTint headerAlign="start" … />
  </AppShellBleed>
</AppShellPage>

headerAlign="start" (or a column's own headerAlign) starts a numeric column's header at the start — icon, name, sort arrow, menu chevron in that order — while its values and its summary stay end-aligned.

Keyboard-continuous load-more

The next page loads as the grid's end nears the edge of its scroll viewport, and

↓ past the last row fetches it too — paging never breaks the keyboard flow, and the two share one guard, so a page is requested once. While it loads, skeleton rows the height of real ones are appended to the body. The tail is the shared LoadMore: no button, Try again after a failed fetch (loadMore.error), and nothing once hasMore is false unless you pass loadMore.endLabel.

Responsive revelation

Columns declare a pixel budget (minWidth, default 120) and a posture for what happens when they no longer fit. Data is never silently lost when a viewport narrows, so the default posture is merge:

"hidden" is the only posture that actually removes a value, which is why it is opt-in and why it announces itself. If you choose it, be sure the value is genuinely recoverable elsewhere.

Fill and fit, as in DataList: the primary (first) column takes the width the others leave and its text wraps, anywhere when a single word is wider than the cell; every other column is sized to its content and kept on one line, and a header never breaks.

A merged value wraps inside the primary cell — it does not inherit a mono or end-aligned primary column's one-line posture, and it wears its own column's face. When a sorted column is merged or hidden (or switched off in the column picker), its header and arrow go with it, so the toolbar states the order instead — Sorted by Stage, descending, then Amount, ascending — and the grid is described by that line and by the hidden-columns count.

API Reference

Block footer

footer as an object, for an embedded grid.

Column

mono is for codes and IDs — a reference, a key — and styles body cells only; the header stays in the sans face. A number (a count, a date, an amount) is numeric: its cells and its header align to the end unless the column sets its own align, and its digits line up in tabular-nums in the regular font. icon puts the field's type glyph before the header label.

Accessibility

• Real role="grid" semantics on a native table: columnheader/gridcell, the primary column's cells as rowheader, aria-colcount and aria-rowcount with TRUE totals (ariaRowCount/ariaColCount when only some rows or columns are loaded; −1 while more rows exist and no total is given), aria-rowindex/aria-colindex on every row and cell, and aria-readonly on non-editable cells.
• One roving tab stop for the whole grid, kept by row id and column key (never by index), so it survives a refetch that moves its row. It roves over the header row, the group rows, the body and the summary row; the sort buttons, menu chevrons, resize handles and checkboxes inside are not stops of their own, and neither is anything a body cell renders (a link chip, a person chip, a checkbox): Alt+Enter on any cell (and Enter on a read-only one) moves into its first one, ←/ → step through them and Escape returns to the cell, so Tab leaves the grid from any cell. Arrows move the active cell (RTL-aware); a windowed-out target scrolls in and takes focus as it mounts. Tab back into the grid returns to the cell that was active, scrolled back in when its row or column was windowed out meanwhile.
• The grid is its own stacking context: its sticky header, summary row and frozen columns never paint over the page's floating parts (an ActionBar).
• Enter/F2 opens the cell editor and suspends grid navigation; Escape closes it and restores focus to the cell; edit-mode entry announces politely.
• Multi-key sort headers carry aria-sort and a visible ordinal per key; shift-click adds a secondary key. Each sort button is named Sort by <column>. Sorted columns always show ↑/↓; an unsorted sortable column's ⇅ stays transparent until the header is hovered (fine pointers only) or its button has keyboard focus, so touch shows only the active arrows and unsortable columns show nothing — the same header parts as DataList.
• Responsive revelation never hides data silently: merge (the default) stacks the value into the primary cell with its header as a visually hidden prefix (Stage: Open), and the only posture that drops a column (mobile: "hidden") reports the count in the toolbar. The grid's aria-describedby points at that count, and at the "Sorted by …" line when a sorted column has left the header row.
• The scroll viewport is keyboard-reachable exactly when it scrolls, and the roving cell's focus outline is pulled inside so the viewport cannot clip it.

The states the verification lanes exercise for this item (generated from component-contracts.json):

Column resize handle

ColumnResizeHandle (in data-table-parts) is the header's trailing-edge grip: a separator with aria-orientation="vertical" and its aria-valuenow/min/max, named Resize Qty. Standalone it is a tab stop with ←/→ (8px, Shift 32px) and

Home/End; inside the grid the same steps run from the focused header with Alt. Its hit area is 24px wide.

Summary row

GridSummaryCell (in data-table-parts) is one footer cell: a quiet Select of the column's summaryOptions (with a built-in None) named Sum of Qty, and the host's result beside it. An unsummarised cell shows Summarize only on hover or focus. The summary row is sticky at the bottom of the viewport and counts as a row in aria-rowcount. The primary column's cell shows summaryRow.label ("412 rows") before its own picker. The cells rove like any row; Enter or Space opens the picker, and closing it returns focus to the cell.

Trailing header control

headerTrailing is a render function: spread the focus props it is handed onto its one control (an "add field" button, or a PopoverTrigger's render button), and the control joins the header row's roving focus — → from the last header reaches it — instead of becoming a second tab stop.

Do / Don't