Headless engine First headless grid

First headless grid

Create a local row model and render an indexed snapshot range.

A headless renderer starts with createLocalRowModel. Add createGrid only when your renderer needs UI state. The grid below is exactly that: 75 services rendered from a plain <table>, with createLocalRowModel driving sort and filter and createGrid driving row selection.

setQuery does not settle synchronously in the general case — the model rebuilds cooperatively, yielding between slices so a large query cannot block the frame, and publishes progress and failures through status. Sort-only and filter-only changes on ungrouped data are the exception, including typing into the filter here: each re-orders or re-selects rows the model has already indexed, so it settles synchronously with no rebuilding phase. Grouped and mixed changes still rebuild cooperatively — see Snapshot & subscribe for a demo. Two things are still worth doing, and the example does both: select what you subscribe to, so a cooperative rebuild elsewhere doesn't re-render you on every slice, and read status, so a failed rebuild doesn't leave stale rows on screen with nothing to say so.

Headless custom renderer

Drive your own markup from the @pretable/core row model with useSyncExternalStore — no grid renderer involved.

.md

"use client";

import { useCallback, useEffect, useState, useSyncExternalStore } from "react";

import { createGrid, createLocalRowModel } from "@pretable/core";

import { columns } from "./columns";
import { services } from "./data";

type ColumnId = (typeof columns)[number]["id"];

export function HeadlessTable() {
  const [rowModel] = useState(() =>
    createLocalRowModel({ columns, rows: services }),
  );
  const [grid] = useState(() => createGrid({ columns, rowModel }));

  // Subscribe to the SNAPSHOT, not to the whole state. `setQuery` settles
  // cooperatively: while it rebuilds, the model publishes a fresh state object
  // per slice carrying `rebuilding` progress, and `snapshot` keeps pointing at
  // the current rows until the new ones swap in. Reading `getState` directly
  // would hand useSyncExternalStore a new identity on every slice and re-render
  // every row for no visual change; reading `.snapshot` bails out on identity
  // and renders once, when the result is ready. Read `getState().status`
  // instead when you want to show rebuild progress.
  const readSnapshot = useCallback(
    () => rowModel.getState().snapshot,
    [rowModel],
  );
  const snapshot = useSyncExternalStore(
    rowModel.subscribe,
    readSnapshot,
    readSnapshot,
  );
  useSyncExternalStore(grid.subscribe, grid.getState, grid.getState);

  // Read `status` too, because a rebuild can FAIL. On `error` the model keeps
  // publishing the last snapshot that committed, so a renderer that ignores it
  // shows stale rows with nothing to say so.
  //
  // Select a STRING, for the same reason the snapshot is selected above: it is
  // `""` through every slice of a healthy rebuild, so the store bails out on
  // equality and this costs no extra render at all.
  //
  // Selecting the status object, or its `completedRows`/`totalRows`, would
  // re-render per slice. Even selecting `status.kind` is worse than it looks:
  // whether an intermediate `rebuilding` state is published before the rebuild
  // finishes depends on how the work sliced, so the render count becomes 1 or 2
  // run to run — measured here at 1 extra render in 6. That is why this example
  // reports failures but not progress. Show progress by putting it in its own
  // component, so a slice re-renders that and not the table.
  const readErrorText = useCallback(() => {
    const status = rowModel.getState().status;
    return status.kind === "error"
      ? `${status.error.code}: ${status.error.message}`
      : "";
  }, [rowModel]);
  const errorText = useSyncExternalStore(
    rowModel.subscribe,
    readErrorText,
    readErrorText,
  );

  // Dispose on a REAL unmount, not on StrictMode's rehearsal.
  //
  // React StrictMode mounts, unmounts and remounts every component in dev, and
  // `useState` hands these same instances back to the remount — so the obvious
  // `() => rowModel.dispose()` cleanup destroys objects the component is about
  // to keep using, and the next render works against a dead model. Deferring by
  // a microtask lets the remount cancel it; a real unmount has no remount to
  // cancel it, so both are still released.
  //
  // `@pretable/react` exports `useDisposeOnUnmount` for exactly this. It is
  // written out here because this example takes only `@pretable/core` — the
  // point being that the engine needs no renderer — and the pattern is short
  // enough to own.
  const pendingDisposal = useState(() => new Set<{ dispose: () => void }>())[0];
  useEffect(() => {
    pendingDisposal.delete(grid);
    pendingDisposal.delete(rowModel);
    return () => {
      pendingDisposal.add(grid);
      pendingDisposal.add(rowModel);
      queueMicrotask(() => {
        if (pendingDisposal.delete(grid)) grid.dispose();
        if (pendingDisposal.delete(rowModel)) rowModel.dispose();
      });
    };
  }, [grid, pendingDisposal, rowModel]);

  // Each toggleRowSelection range is a single full-width row
  // (startRowId === endRowId), so selected ids read back directly.
  const toggleSort = (columnId: ColumnId) => {
    const current = snapshot.query.sort.find(
      (entry) => entry.columnId === columnId,
    );
    const next =
      current === undefined
        ? "asc"
        : current.direction === "asc"
          ? "desc"
          : null;
    rowModel.setQuery({
      ...snapshot.query,
      sort: next ? [{ columnId, direction: next }] : [],
    });
  };

  return (
    <div>
      <label style={{ display: "block", marginBottom: 8, fontSize: 13 }}>
        Filter by team{" "}
        <input
          aria-label="Filter by team"
          defaultValue=""
          onChange={(e) =>
            rowModel.setQuery({
              ...snapshot.query,
              filters: e.target.value
                ? [
                    {
                      columnId: "team",
                      operator: "contains",
                      value: e.target.value,
                    },
                  ]
                : [],
            })
          }
        />
      </label>
      {/* Two regions, never one element that switches `role`. A single <p>
          whose role flipped would be the SAME node after reconciliation —
          React would call setAttribute on it — and assistive tech generally
          does not re-map a node it has already exposed. */}
      <p role="status" style={{ fontSize: 13 }}>
        {snapshot.visibleRowCount} of {snapshot.sourceRowCount} rows
      </p>
      {errorText === "" ? null : (
        <p
          role="alert"
          style={{ fontSize: 13, color: "var(--pretable-text-error, #b3261e)" }}
        >
          Query failed ({errorText}). The rows below are from the last query
          that committed.
        </p>
      )}
      <table>
        <thead>
          <tr>
            {columns.map((c) => {
              const sortEntry = snapshot.query.sort.find(
                (entry) => entry.columnId === c.id,
              );
              return (
                <th key={c.id} scope="col">
                  <button type="button" onClick={() => toggleSort(c.id)}>
                    {c.header ?? c.id}
                    {sortEntry
                      ? sortEntry.direction === "asc"
                        ? " ▲"
                        : " ▼"
                      : ""}
                  </button>
                </th>
              );
            })}
          </tr>
        </thead>
        <tbody>
          {snapshot
            .range(0, snapshot.visibleRowCount)
            .filter((entry) => entry.kind === "data")
            .map(({ rowId, row }) => (
              <tr
                key={rowId}
                aria-selected={grid.isRowSelected(rowId)}
                onClick={() => grid.toggleRowSelection(rowId)}
              >
                {columns.map((c) => (
                  <td key={c.id}>{String(c.accessor(row))}</td>
                ))}
              </tr>
            ))}
        </tbody>
      </table>
    </div>
  );
}

The rest of this page walks through how that table is built, piece by piece.

Create typed columns and a row model

The example above declares its columns exactly this way — columns.ts calls createColumnHelper<Service>() once, then column.accessor(...) per field:

columns.ts

import { createColumnHelper, createLocalRowModel } from "@pretable/core";
 
interface Service {
  id: string;
  name: string;
  latencyMs: number;
}
 
const column = createColumnHelper<Service>();
const columns = [
  column.accessor("name", { type: "text", header: "Service" }),
  column.accessor("latencyMs", {
    type: "number",
    header: "Latency",
  }),
] as const;
 
const rowModel = createLocalRowModel({ rows, columns });

The helper preserves each column's ID and value type. createLocalRowModel infers the row, row ID, and complete column tuple — nothing above is manually typed.

The example's readSnapshot callback, passed to useSyncExternalStore, is this in its shortest form:

tsx

const state = useSyncExternalStore(
  rowModel.subscribe,
  rowModel.getState,
  rowModel.getState,
);
const snapshot = state.snapshot;

getState() is referentially stable until the committed snapshot or observable status changes. The example goes one step further and selects .snapshot directly rather than the whole state — see Snapshot & subscribe for why that's what keeps a rebuild from re-rendering the table on every slice.

Render an indexed range

The <tbody> in the example above requests only the half-open window it plans to render. Bounds are clamped to [0, snapshot.visibleRowCount]:

tsx

const start = 0;
const end = Math.min(snapshot.visibleRowCount, 100);
 
<tbody>
  {snapshot.range(start, end).map((entry) =>
    entry.kind === "data" ? (
      <tr key={entry.rowId}>
        <td>{entry.row.name}</td>
        <td>{entry.row.latencyMs}</td>
      </tr>
    ) : (
      <tr key={entry.groupId}>
        <th colSpan={2}>{String(entry.value)}</th>
      </tr>
    ),
  )}
</tbody>;

Add UI state when needed

Row selection in the example — click a row, and aria-selected follows — is createGrid plus grid.toggleRowSelection. Focus works the same way:

import { createGrid } from "@pretable/core";
 
const grid = createGrid({ rowModel, columns });
grid.setFocus({ ref: { kind: "data", rowId: "svc-1" }, columnId: "name" });

The UI grid does not own rows or query state. For the complete typed column and row-model contracts, see the API reference.

Snapshot & subscribe

Indexed row-model and UI-state snapshots.

Actions

Query, transaction, expansion, selection, and layout commands.

Create typed columns and a row model

Subscribe

Render an indexed range

Add UI state when needed

Next

Snapshot & subscribe

Actions