The PretableSurface component

<PretableSurface> is the production grid component: indexed rendering, selection, keyboard navigation, editing, clipboard, filters, sorting, grouping, native date and number formatting, and custom presentation hooks.

Declarative rows mode

"use client";

import { PretableSurface } from "@pretable/react";

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

const VIEWPORT_HEIGHT = 260;

export function EventGrid() {
  return (
    <PretableSurface
      ariaLabel="Live events"
      rows={events}
      columns={columns}
      getRowId={(row) => row.id}
      viewportHeight={VIEWPORT_HEIGHT}
    />
  );
}

That's the whole recipe — typed columns, rows, and ariaLabel:

import { createColumnHelper } from "@pretable/core";
import { PretableSurface } from "@pretable/react";
 
interface Event {
  id: string;
  timestamp: string;
  message: string;
}
 
const column = createColumnHelper<Event>();
const columns = [
  column.accessor("timestamp", { type: "text", header: "Time" }),
  column.accessor("message", { type: "text", header: "Message" }),
] as const;
 
export function EventGrid({ events }: { events: Event[] }) {
  return (
    <PretableSurface
      ariaLabel="Live events"
      rows={events}
      columns={columns}
      viewportHeight={520}
    />
  );
}

The surface creates one local row model for its lifetime and reconciles later rows props by stable ID. This is the default application path. Rows with a string or number id need no identity prop; pass getRowId for another stable key.

Explicit-model mode

Use explicit ownership for streaming or other imperative producers. Below, a chat grid owns its row model directly and connects it to a stream with connectElementStream — the same explicit-model shape, applied to @pretable/stream-adapter's highest-frequency case:

"use client";

import { connectElementStream } from "@pretable/stream-adapter";
import { PretableSurface, useDisposeOnUnmount } from "@pretable/react";
import { createLocalRowModel } from "@pretable/core";
import { useEffect, useMemo } from "react";

import { columns, type ChatRow } from "./columns";
import {
  responseEventsToChatRows,
  type ChatResponseEvent,
} from "./response-events-to-chat-rows";

export type OpenChatResponseEvents = (input: {
  readonly model: string;
  readonly prompt: string;
}) =>
  AsyncIterable<ChatResponseEvent> | Promise<AsyncIterable<ChatResponseEvent>>;

export function ChatGrid({
  prompt,
  openResponseEvents,
}: {
  prompt: string;
  openResponseEvents: OpenChatResponseEvents;
}) {
  const rowModel = useMemo(
    () => createLocalRowModel({ rows: [], columns, getRowId: (row) => row.id }),
    [],
  );

  useEffect(() => {
    let disposed = false;
    let connection: ReturnType<typeof connectElementStream> | undefined;
    void (async () => {
      const stream = await openResponseEvents({
        model: "gpt-5",
        prompt,
      });
      const rows: AsyncIterable<ChatRow> = responseEventsToChatRows(stream);
      connection = connectElementStream(rowModel, rows);
      if (disposed) connection.dispose();
    })();
    return () => {
      disposed = true;
      connection?.dispose();
    };
  }, [openResponseEvents, prompt, rowModel]);

  // NOT `useEffect(() => () => rowModel.dispose())`: StrictMode rehearses an
  // unmount in dev, `useMemo` hands the same model back to the remount, and the
  // grid then renders nothing at all. `useDisposeOnUnmount` defers the disposal
  // by a microtask so a remount can cancel it.
  useDisposeOnUnmount(rowModel);

  return (
    <PretableSurface
      ariaLabel="Streaming chat"
      model={rowModel}
      viewportHeight={320}
    />
  );
}

The shape in general:

const rowModel = createLocalRowModel({ rows: [], columns });
const connection = connectElementStream(rowModel, stream);
 
<PretableSurface
  ariaLabel="Streaming events"
  model={rowModel}
  viewportHeight={520}
/>;

The modes are mutually exclusive: do not pass rows or getRowId with model. Optional columns in model mode may change presentation, not accessors, comparators, filters, aggregates, or IDs.

Configuration

Rows-mode edit callbacks are proposals: update your rows value and let the next prop reconcile. Explicit-model edits validate the batch and publish one row-model transaction.

Native dateFormat / numberFormat options and locale format compatible cells, inherited group aggregates, built-in clipboard text, and CSV through one precedence pipeline. format and formatAggregate remain the custom overrides. Canonical date behavior is presentation-only here: raw values stay YYYY-MM-DD | null, and external query authority is never reapplied locally. See Date formatting and Number formatting.

For common semantic presentations, PretableBadge, PretableDelta, PretableEntity, and PretableStatus provide theme-aware contrast, direction markers, primary/secondary text, and state dots without rebuilding cell behavior. See Cell presentations.

Controlled state and ownership

The rows-mode query/onQueryChange pair owns filters, sort, and grouping together. The state prop controls UI interaction and column-layout slices. In explicit-model mode, application code sends query and row mutations to rowModel; an onGridReady handle remains UI-only.

See Row grouping and aggregation for typed grouping, aggregate, expansion, and group-panel contracts.

Server-applied filtering and sorting

processing declares whether filter and sort work was performed by the local engine or an external authority; resultMeta then describes the result those rows came from, and dataState says where its request stands. Both are acted on in rows mode: the surface stops the engine applying query.filters and query.sort while continuing to publish them, so the funnel, onQueryChange, and aria-sort are unchanged. All of it — query ownership, totals, the lifecycle phases, and renderBodyState — is documented against a live endpoint in Server-side data.

Telemetry

Telemetry distinguishes source/logical rows from the currently rendered viewport range. Keep onTelemetryChange stable with useCallback; it may fire during hot rendering paths.

Rejected writes

An invalid rows, derivations, or query update is a rejected write: the grid keeps its last-good value and stays alive rather than unmounting. The console warning that accompanies a rejection latches per fault kind — it fires once and stays quiet — so it is a debugging aid, not a signal your code can act on. The programmatic signal is the rejected-writes record: onRejectedWriteChange fires on every transition, including recovery, with a per-kind record — { rows, derivations, query }, each null when that slot is in sync or a PretableRejectedWrite (kind, code, message, and columnId when one column is at fault) describing the most recent rejection. Nothing latches: every rejection replaces the record, and a slot clears on its own when a valid value lands.

import { useState } from "react";
import { PretableSurface, type PretableRejectedWrites } from "@pretable/react";
 
function Positions({ rows }: { rows: readonly Position[] }) {
  const [rejected, setRejected] = useState<PretableRejectedWrites | null>(null);
  return (
    <>
      {rejected?.rows && <StaleBanner reason={rejected.rows.message} />}
      <PretableSurface
        ariaLabel="Positions"
        rows={rows}
        columns={columns}
        getRowId={(row) => row.id}
        onRejectedWriteChange={setRejected}
      />
    </>
  );
}

In explicit-model mode the same record is model.rejectedWrites on usePretable's return, and rejections inside useLocalRowModel surface through it too. Fatal faults — a disposed model, reentrant mutation, or a foreign error — still throw; only recoverable prop and model writes become rejections.

Streaming guidance

Use the rows prop for normal React updates. For high-frequency streams, own a row model and connect @pretable/stream-adapter to it. The adapter animation-frame batches transactions while the surface requests only its indexed viewport range.

See also

• <Pretable> component
• Selection
• Editing
• Clipboard
• Custom rendering
• Number formatting
• Date formatting
• Streaming
• API reference