DataGrid

ARIA data grid foundation for spreadsheet-like datasets with stable row identity, explicit column widths, keyboard navigation, row selection, cell/range selection, and pinned-column metadata.

See the tabular family boundaries. DataGrid is the interactive-grid alternative to the native Table and DataTable families; choose Table for bespoke native markup or DataTable for data-shaped native tables.

Usage

<script lang="ts">
  import { DataGrid } from '@lostgradient/cinder';
  import type { DataGridColumnDef } from '@lostgradient/cinder';

  type Order = { id: string; customer: string; status: string };

  const columns: DataGridColumnDef<Order>[] = [
    { key: 'id', header: 'Order', width: 120, pin: 'left' },
    { key: 'customer', header: 'Customer', width: 220 },
    { key: 'status', header: 'Status', width: 140 },
  ];

  const rows: Order[] = [
    { id: 'ORD-1001', customer: 'Ada Lovelace', status: 'Packed' },
    { id: 'ORD-1002', customer: 'Grace Hopper', status: 'Shipped' },
  ];
</script>

<DataGrid {columns} {rows} getRowId={(row) => row.id} aria-label="Orders" />

Guidance

Use When

• Rendering an interactive tabular surface that needs grid semantics instead of native table semantics.
• You need built-in row selection, cell focus, range selection, copy behavior, and inline editing.

Avoid When

• You only need a semantic read-only table — use DataTable or the Table family instead.

Keyboard navigation

DataGrid owns a single root tab stop (the role="grid" element itself) and moves a virtual "active cell" with aria-activedescendant instead of putting body cells in the tab order — the same roving-focus pattern the ARIA grid pattern describes. This table is the complete base keyboard contract; Editing and header focus, resize, and reorder layer their own keys on top of it, scoped to when a cell is editing or a header is focused.

Clicking a cell mirrors the keyboard equivalents above for the cell range: a plain click moves the active cell (and, in 'single'/'multiple' selectionMode, selects that cell's row), Shift-click extends the cell range the same way Shift+Arrow does, and Ctrl/Cmd-click toggles the cell into the range the same way Ctrl+Enter does. Row selection itself only follows a plain or Ctrl/Cmd-click/Enter (replace or toggle) — Shift-click/Enter extends the cell range without changing which rows are selected, since row selection has no notion of a contiguous "range" the way cells do.

Editing

Mark a column editable: true to let its cells enter edit mode. DataGrid tracks the editing cell by stable row key plus column key — not by visual row/column index — so sorting and virtualization never lose an in-progress edit.

<script lang="ts">
  import { DataGrid } from '@lostgradient/cinder';
  import type { DataGridColumnDef } from '@lostgradient/cinder';

  type Order = { id: string; customer: string; total: number };

  let orders = $state<Order[]>([
    { id: 'ORD-1001', customer: 'Ada Lovelace', total: 124 },
    { id: 'ORD-1002', customer: 'Grace Hopper', total: 256 },
  ]);

  const columns: DataGridColumnDef<Order>[] = [
    { key: 'customer', header: 'Customer', width: 220, editable: true },
    { key: 'total', header: 'Total', width: 120, editable: true },
  ];

  function handleCellEdit(row: Order, columnKey: string, value: unknown): void {
    orders = orders.map((order) =>
      order.id === row.id ? { ...order, [columnKey]: value } : order,
    );
  }
</script>

<DataGrid
  rows={orders}
  {columns}
  getRowId={(order) => order.id}
  onCellEdit={handleCellEdit}
  aria-label="Orders"
/>

• The edit surface is always Cinder's own Input, never a bespoke <input>. Its type comes from the column's editType ('text' or 'number') when set, otherwise from typeof the cell's current value — a number value resolves to type="number", everything else resolves to type="text".
• onCellEdit(row, columnKey, value) fires on commit. value is typed for the resolved edit type: a 'number' column emits a number, or undefined for an empty draft (never NaN); every other column emits the edited string. DataGrid never mutates the rows prop — apply value to your own data, as above.
• A column that also supplies a custom cell snippet keeps rendering that snippet while editing, with editing: true in its context, instead of DataGrid's built-in Input; that column owns its own edit UI.

Resizing and reordering columns

Column resizing and reordering are both off by default so an existing grid renders unchanged. Opt in per grid with resizableColumns and reorderableColumns; a column opts out of resizing individually with resizable: false. columnSizing and columnOrder are $bindable, mirroring sortModel — DataGrid assigns them directly after a gesture and also calls onColumnSizingChange / onColumnOrderChange.

<script lang="ts">
  import { DataGrid } from '@lostgradient/cinder';
  import type { DataGridColumnDef, DataGridColumnSizing } from '@lostgradient/cinder';

  type Order = { id: string; customer: string; total: number };

  const columns: DataGridColumnDef<Order>[] = [
    { key: 'id', header: 'Order', width: 120, pin: 'left' },
    { key: 'customer', header: 'Customer', width: 220 },
    { key: 'total', header: 'Total', width: 120 },
  ];

  let columnSizing = $state<DataGridColumnSizing>({});
  let columnOrder = $state<readonly string[]>([]);
</script>

<DataGrid
  {columns}
  rows={[]}
  getRowId={(order: Order) => order.id}
  resizableColumns
  reorderableColumns
  bind:columnSizing
  bind:columnOrder
  aria-label="Orders"
/>

• Resizing (pointer). A resizable header cell gets a role="separator" handle (cursor: col-resize) at its trailing edge. Dragging it live-updates the column's width, clamped to minWidth/maxWidth; the drag commits into columnSizing/onColumnSizingChange on pointerup, not on every pointermove. The handle stops the pointer event from reaching the header, so dragging it never triggers a sort.
• Resizing (keyboard). See the keyboard table below — Shift+ArrowLeft/Right resizes the focused header column by 10px, clamped the same way.
• Reordering (pointer). Dragging a header cell past the midpoint of a sibling shows a drop indicator and reorders on drop. Reordering is constrained to within the same pin group — a column can only change position among columns that share its pin value (unpinned columns never reorder in front of or behind a pinned column, and the two pinned groups never mix). A small movement below the drag threshold is still treated as a click, so sorting a sortable column is unaffected.
• Reordering (keyboard). Ctrl/Cmd+Shift+ArrowLeft/Right moves the focused header column one position within its pin group.
• Virtualized columns. Both gestures work with virtualizeColumns — the column virtualizer is told about every resize so its measured track sizes and total width stay correct, not just the resized cell's own CSS width.
• Right-to-left. The resize handle still sits at the header cell's trailing edge (which is the visual left in RTL) and pointer-drag direction is inverted automatically so dragging toward the column's interior always widens it, matching LTR. Reordering is inverted the same way — dragging toward the visual left in RTL moves a column later in columnOrder, not earlier, so a drop always lands on the side of the target the pointer is actually over.

Keyboard and focus contract

Focus always returns to the grid root after a commit or cancel, so role="grid" keyboard navigation (aria-activedescendant) keeps working the same way it does for click- and arrow-driven cell focus.

Header focus, resize, and reorder by keyboard

DataGrid's roving focus normally only ever lands on body cells — there is no separate "header is focused" mode until a grid opts into resizableColumns or reorderableColumns. When one of those is set:

Every resize or reorder from the keyboard is announced through the same live region used elsewhere in DataGrid (for example, "Customer column resized to 190 pixels" or "Customer column moved to position 2").

This is intentionally scoped to the column of the currently active cell rather than a fully independent header roving-tabindex, since DataGrid has no such concept outside of resizing/reordering: Shift+ArrowLeft/Shift+ArrowRight on a body cell keeps its existing meaning (extending the cell selection range) and is completely unaffected — the resize/reorder shortcuts only ever fire while header focus is active.

Search

Opt in with search. DataGrid renders a toolbar — built from Cinder's own Toolbar, SearchField, and Button — directly above the grid, outside the role="grid" element. Off by default: a grid that doesn't pass search renders no toolbar, computes no matches, and starts no timers.

<script lang="ts">
  import { DataGrid } from '@lostgradient/cinder';
  import type { DataGridColumnDef } from '@lostgradient/cinder';

  type Order = { id: string; customer: string; status: string };

  const columns: DataGridColumnDef<Order>[] = [
    { key: 'id', header: 'Order', width: 120, pin: 'left' },
    { key: 'customer', header: 'Customer', width: 220 },
    { key: 'status', header: 'Status', width: 140 },
  ];

  const rows: Order[] = [
    { id: 'ORD-1001', customer: 'Ada Lovelace', status: 'Packed' },
    { id: 'ORD-1002', customer: 'Grace Hopper', status: 'Shipped' },
  ];
</script>

<DataGrid {columns} {rows} getRowId={(row) => row.id} search aria-label="Orders" />

• Matching. 300ms after the user stops typing, DataGrid checks every column's resolved value (through the column's getValue when supplied, otherwise the row property) as a case-insensitive substring match — over every row in sorted order and every column, regardless of what row/column virtualization currently has rendered. A matching cell gets the cinder-data-grid__cell--search-match class; the current match additionally gets cinder-data-grid__cell--search-match-current.
• Navigation. The toolbar's previous/next buttons, or Enter / Shift+Enter in the search field, step through matches with wraparound. Stepping (and settling on the first match once typing stops) makes that cell the active cell and scrolls it into view through the same virtualization-adapter scroll-to-index path arrow-key navigation already uses, so it works identically whether or not virtualizeRows / virtualizeColumns is on.
• Announcements. Match position ("Match 3 of 12") and "No matches" are announced through DataGrid's existing live region.
• Coexistence. Search recomputes from whatever rows/columns DataGrid currently has, so committing a cell edit or changing sortModel updates matches and highlighting automatically — no extra wiring required.
• The search field's accessible name is derived from the grid's own aria-label (e.g. "Search Orders") and it sets aria-controls to the grid.

Zoom

Opt in with zoom (a percentage, default 100). It multiplies row height, header height, column width, and cell text size together — everything scales as one unit, not independently.

<script lang="ts">
  import { DataGrid } from '@lostgradient/cinder';
  import type { DataGridColumnDef } from '@lostgradient/cinder';

  type Order = { id: string; customer: string; status: string };

  const columns: DataGridColumnDef<Order>[] = [
    { key: 'id', header: 'Order', width: 120, pin: 'left' },
    { key: 'customer', header: 'Customer', width: 220 },
    { key: 'status', header: 'Status', width: 140 },
  ];

  const rows: Order[] = [
    { id: 'ORD-1001', customer: 'Ada Lovelace', status: 'Packed' },
    { id: 'ORD-1002', customer: 'Grace Hopper', status: 'Shipped' },
  ];

  let zoom = $state(100);
</script>

<DataGrid {columns} {rows} getRowId={(row) => row.id} bind:zoom aria-label="Orders" />

• Range. zoom is clamped to [50, 200]. A non-finite value (NaN, Infinity, a non-number) is ignored and DataGrid falls back to 100, warning in development — the same pattern rowHeight uses for an invalid value.
• $bindable. Mirrors sortModel/columnSizing: DataGrid assigns zoom directly after a zoom-control interaction (see zoomControls below), in addition to calling onZoomChange.
• Base pixels stay base pixels. columnSizing (see Resizing and reordering columns) always stays in unscaled base pixels, whatever zoom currently is — only the rendered, on-screen size is scaled. A pointer resize under a non-100% zoom still commits the same base width a 100%-zoom resize would for the same visual drag distance; a keyboard resize step is always exactly 10 base px, regardless of zoom.
• Virtualization. virtualizeRows/virtualizeColumns measure and scroll using the scaled row height and column widths, so virtualized and non-virtualized grids stay visually consistent at any zoom level.

Toolbar counts and zoom controls

Opt in with zoomControls to render a row count, a visible column count, and zoom in/out buttons in the same toolbar search uses — set both to combine them in one toolbar, or either alone. With neither search nor zoomControls set, DataGrid renders no toolbar DOM at all.

<DataGrid {columns} {rows} getRowId={(row) => row.id} zoomControls bind:zoom aria-label="Orders" />

• Counts. The row count is the current rows.length; the column count is the current number of visible (rendered) columns — left-pinned, unpinned, and right-pinned together.
• Zoom buttons. "Zoom out" and "Zoom in" step zoom by 10 percentage points, clamped to [50, 200]; each is disabled at its respective bound. Both have accessible names and neither is aria-controls-wired to the grid (they act on the grid as a whole, not a scoped region of it).
• Announcements. Changing the zoom level announces "Zoom <n>%" through DataGrid's existing live region.

Parsing CSV/TSV text

parseDelimitedText(text, { delimiter }) is a pure parsing utility — not a new component or a props-driven "preset" — that turns CSV/TSV (or any single-character-delimited) text into { columns, rows } for DataGrid's existing columns/rows props, unchanged.

<script lang="ts">
  import { DataGrid, parseDelimitedText } from '@lostgradient/cinder';

  const csv = `id,customer,status\nORD-1001,Ada Lovelace,Packed\nORD-1002,Grace Hopper,Shipped\n`;
  const { columns, rows: parsedRows } = parseDelimitedText(csv, { delimiter: ',' });

  // Parsed rows have no built-in stable identity, so derive one — here, an
  // index — before handing them to DataGrid's `getRowId`.
  const rows = parsedRows.map((row, index) => ({ ...row, __rowIndex: String(index) }));
</script>

<DataGrid {rows} {columns} getRowId={(row) => row.__rowIndex} aria-label="Imported orders" />

• Delimiter is explicit. delimiter is required and used exactly as given — parseDelimitedText never guesses a delimiter from the input. Pass ',' for CSV or '\t' for TSV.
• Header row. The first parsed row is always the header row, supplying both key and header for every derived DataGridColumnDef. There is no positional/headerless mode.
• Quoting. A quoted field ("…") may contain the delimiter, embedded newlines (\n or \r\n), and an escaped double quote written as "".
• Line endings. Both \n and \r\n are accepted, including a mix of the two in the same input.
• Blank lines are skipped. A line with nothing at all between two line endings — including the header line — is dropped rather than becoming an empty row/column. A line that has delimiters but empty values (e.g. ,,) is not blank and is kept.
• Duplicate/empty headers. Header names are trimmed when deriving each column's key. An empty header (after trimming) falls back to column_<n> (1-indexed by position); a key that collides with one already assigned gets _2, _3, … appended, deterministically by left-to-right header order. The displayed header keeps the original text (even duplicated, or empty once a key was defaulted) — only the internal key is disambiguated.
• Values are always strings. parseDelimitedText never infers or coerces a numeric/date column — convert one yourself, either by mapping rows before handing them to DataGrid or with that column's getValue.
• getRowId. Parsed rows have no id of their own. Either pick a column you know is unique in your data (getRowId={(row) => row.email}) or derive one from position, as in the example above.

Unsupported behavior and limitations

• Extremely tall/wide content is not clamped. virtualizeRows/virtualizeColumns render actual-size row and column tracks and translate them into view — they never fake or clamp the grid's total scrollable height/width the way some virtualization libraries do at extreme row/column counts. Every browser has a hard ceiling on an element's rendered size, past which layout silently breaks (rows overlap, scroll position stops tracking, or the element is clipped to the ceiling): roughly 17,895,697px in Gecko (Firefox) and roughly 33,554,428px in Chromium and WebKit (Chrome, Edge, Safari). At the default 44px row height that's roughly 406,000 rows in Gecko and roughly 762,000 rows in Chromium/WebKit before row virtualization's total height hits the ceiling — proportionally fewer at a larger rowHeight or a zoom above 100%, since both scale the total height directly. This is a deliberate decision, not an oversight: DataGrid does not clamp, cap, or otherwise paper over the ceiling, because doing so would silently misrepresent the data's true size (a clamped scrollbar no longer means what it says) for a case only reachable with unrealistically large datasets. If your data can approach these row/column counts, page or window it server-side (or client-side ahead of DataGrid) so the grid itself never receives more rows/columns than a browser can lay out correctly.
• Row/column virtualization requires a browser. virtualizeRows/virtualizeColumns need real ResizeObserver/scroll measurements and are inert during server rendering — see virtualization-adapter.svelte.ts's SSR accessors, which report fixed aggregate sizes and empty virtual windows instead of touching the DOM. A server-rendered grid with virtualization enabled renders its full row/column set on the server and virtualizes only after hydration in the browser.
• Search and zoom scan/scale the full dataset, not just what's rendered. search computes matches over every row and column regardless of virtualization (see Search), and zoom scales every row's height into the virtualizer's total-height calculation (see Zoom) — both cost is proportional to the full rows/columns size, not the virtualized window, on top of the row/column-count ceiling above.