Snapshot & subscribe

The row model and UI grid are independent observable stores. Subscribe only to the state your renderer uses.

A setQuery that changes row grouping does not settle synchronously — the model rebuilds cooperatively, yielding between slices so a large query cannot block the frame. Sort-only and filter-only changes on ungrouped data are the exception: each re-orders or re-selects rows the model has already indexed, so it settles synchronously and never publishes a rebuilding phase — plain sorting and filtering need no progress UI. Grouped and mixed changes still rebuild cooperatively. On a small dataset even the cooperative rebuild is over before a human (or React) can see it happen, which is why the button below groups 150,000 rows instead of 75: watch status cycle through rebuilding with a live percentage, then settle back to ready.

"use client";

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

import { createLocalRowModel } from "@pretable/core";
import { useDisposeOnUnmount } from "@pretable/react";

import { columns } from "./columns";
import { ORDER_COUNT, orders } from "./data";
import { RebuildProgress } from "./RebuildProgress";

const PREVIEW_ROWS = 8;

export function RebuildProgressDemo() {
  const [rowModel] = useState(() =>
    createLocalRowModel({ columns, rows: orders }),
  );
  useDisposeOnUnmount(rowModel);

  // Selecting `snapshot` (not the whole state) means this component bails
  // out on identity between rebuild slices — it only renders once, when the
  // grouping change actually lands. `RebuildProgress` above is the one
  // re-rendering on every slice in the meantime.
  const readSnapshot = useCallback(
    () => rowModel.getState().snapshot,
    [rowModel],
  );
  const snapshot = useSyncExternalStore(
    rowModel.subscribe,
    readSnapshot,
    readSnapshot,
  );

  const [grouped, setGrouped] = useState(false);

  // A GROUPING change, not a filter or a sort: both of those settle
  // synchronously on ungrouped data (the sort fast path and the filter fast
  // path each require `rowGroups.length === 0`), so neither could
  // demonstrate the progress readout anymore. Grouping never takes a fast
  // path — it always rebuilds cooperatively — which is exactly why it is the
  // vehicle here.
  const toggleGrouped = () => {
    const next = !grouped;
    setGrouped(next);
    rowModel.setQuery({
      ...snapshot.query,
      rowGroups: next ? [{ columnId: "region" }] : [],
    });
  };

  return (
    <div>
      <button type="button" onClick={toggleGrouped}>
        {grouped
          ? "Ungroup"
          : `Group ${ORDER_COUNT.toLocaleString()} orders by region`}
      </button>
      <RebuildProgress rowModel={rowModel} />
      <p style={{ fontSize: 13 }}>
        {snapshot.visibleRowCount.toLocaleString()} rows indexed — showing the
        first {PREVIEW_ROWS}
      </p>
      <table>
        <thead>
          <tr>
            {columns.map((c) => (
              <th key={c.id} scope="col">
                {c.header ?? c.id}
              </th>
            ))}
          </tr>
        </thead>
        <tbody>
          {snapshot
            .range(0, Math.min(PREVIEW_ROWS, snapshot.visibleRowCount))
            .map((entry) =>
              entry.kind === "data" ? (
                <tr key={entry.rowId}>
                  {columns.map((c) => (
                    <td key={c.id}>{String(c.accessor(entry.row))}</td>
                  ))}
                </tr>
              ) : (
                <tr key={entry.groupId}>
                  <td colSpan={columns.length}>
                    {String(entry.value)} ({entry.childCount})
                  </td>
                </tr>
              ),
            )}
        </tbody>
      </table>
    </div>
  );
}

The RebuildProgress readout above is its own component, subscribed only to status. The table underneath it subscribes only to snapshot and never re-renders mid-rebuild. That split is the pattern this page documents.

Row-model state

rowModel.getState() returns { snapshot, status }.

status is a discriminated union, not a string — compare status.kind, never status itself. That's the value the progress readout above is watching climb:

rebuilding does not mean the snapshot is frozen. It means the in-flight query has not been applied yet — the snapshot is still the last one that committed, and mutations keep committing into it meanwhile: setRows, applyTransaction and both expansion paths publish a new snapshot while a rebuild runs. A renderer that stops re-reading the snapshot during a rebuild drops those, which is exactly the streaming-plus-filter case. The table in the example above stays on the last committed result throughout, exactly like this.

completedRows and totalRows count the rebuild's work units, not rows. Grouping and concurrent mutations add units as the transition runs, so totalRows can exceed the source row count and can grow mid-rebuild — which is why the readout above reports a percentage rather than "row 40,000 of 150,000". Use them as a progress ratio; do not label them as rows.

Select what you subscribe to. getState() returns a fresh object on every cooperative slice, so handing it whole to useSyncExternalStore re-renders the consumer on each one. Select the snapshot — stable until the swap — for the table, exactly as the example's RebuildProgressDemo does. For progress or errors, don't select status.kind alone — it can't tell you the percentage — select a derived string built from status, the way RebuildProgress does: `rebuilding:${pct}` while a rebuild is running, or the bare kind otherwise. A string still lets useSyncExternalStore bail out on identity between slices that round to the same percentage, while giving you something a number or the status object itself can't: a value that actually changes as the rebuild progresses. Subscribing to the whole state object instead cost the smaller custom-renderer example ~1.9s of per-slice repainting for a rebuild the model finishes in ~4ms — see that example for the measurement.

A renderer that ignores status altogether shows stale rows after a failed rebuild with nothing to indicate it, because on error the snapshot it is reading is the last one that committed.

Rows are indexed:

snapshot.rowAt(index);
snapshot.range(start, end); // half-open and clamped
snapshot.indexOf({ kind: "data", rowId });
snapshot.dataRowAt(dataIndex);
snapshot.firstDataRow();
snapshot.nextDataRow(ref);

Captured snapshots are immutable revision roots. getState() returns the same object identity until either its snapshot or status changes.

UI-state snapshot

When you create createGrid({ rowModel, columns }), grid.getState() contains only presentation state:

• viewport
• discriminated focus
• indexed selection
• editing
• columnLayout
• the last row-model revision observed by layout

Grid notifications do not proxy row-model notifications. A custom renderer that uses both should subscribe to both stores.

const unsubscribeModel = rowModel.subscribe(render);
const unsubscribeGrid = grid.subscribe(render);
 
function render() {
  const { snapshot, status } = rowModel.getState();
  const ui = grid.getState();
  // Read only the range required by this frame.
}

Unsubscribing is idempotent. No-op commands do not notify.

Server rendering

Create the row model from the same immutable inputs on the server and first client render, and use getState as the server snapshot for useSyncExternalStore.

Next