Concepts

Pretable is built around three layers. Understanding their boundaries makes the rest of the docs easier to navigate. The grid below shows the split in one click: the button flips a single data-theme attribute, and the grid repaints instantly — no JavaScript ever touches a --pretable-* token.

"use client";

import { useState } from "react";

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

import { columns } from "./columns";
import { tasks, type Task } from "./data";

const VIEWPORT_HEIGHT = 220;

export function DarkModeToggleGrid() {
  const [dark, setDark] = useState(false);

  return (
    <div>
      <p style={{ margin: "0 0 8px", fontSize: 13 }}>
        The button below sets <code>data-theme=&quot;dark&quot;</code> on the
        wrapper <code>div</code>, not on <code>&lt;html&gt;</code> — a docs-site
        adaptation so this one grid goes dark without repainting the rest of the
        page. A real app toggles the attribute on <code>&lt;html&gt;</code>{" "}
        instead; that is the pattern this example is standing in for.
      </p>
      <button
        onClick={() => setDark((value) => !value)}
        style={{ marginBottom: 8 }}
        type="button"
      >
        Switch to {dark ? "light" : "dark"}
      </button>
      <div
        data-theme={dark ? "dark" : undefined}
        style={{
          background: "var(--pretable-bg-toolbar)",
          borderRadius: 12,
          padding: 12,
        }}
      >
        <PretableSurface<Task>
          ariaLabel="Tasks"
          columns={columns}
          getRowId={(row) => row.id}
          rows={tasks}
          viewportHeight={VIEWPORT_HEIGHT}
        />
      </div>
    </div>
  );
}

The engine + theming split

@pretable/react is the engine. It handles row virtualization, column layout, focus and selection state, sort and filter dispatch, and the data attributes ([data-pretable-*]) that mark every interactive element. The engine is structurally pure — its inline styles handle position, height, and z-index, but no colors, padding, fonts, or borders. That is why the toggle above never re-renders the engine's own output: the same rows, the same layout, the same DOM structure are there in both modes, only the resolved colors change.

@pretable/ui is the theming layer. It ships CSS files: theme files (themes/pretable.css, themes/excel.css, themes/material.css) declare --pretable-* design tokens at :root (and, for pretable/material, a [data-theme="dark"] block); grid.css is a selector-based skin that targets the engine's data attributes and resolves the tokens. There's no JavaScript theme builder — the button above sets an attribute and stops; everything after that is CSS doing what CSS already does.

The two packages cooperate through a documented contract: the engine emits known data attributes, the theming layer styles them. Either side can be replaced without forking the other — you can ship @pretable/ui with a different design system, or use @pretable/react with hand-rolled CSS, and both still work.

Two CSS-variable namespaces

Pretable uses one CSS-variable namespace exclusively: --pretable-*. All 50 public tokens live there. See the token reference for the full list.

Your application has its own namespace — whatever brand tokens you already use, like --brand-*, --app-*, or your design system's prefix. The two never collide because they're prefix-disjoint. You can theme the grid with Material 3 while your surrounding marketing site uses your own brand tokens, and there's no leakage either direction.

Three runtime axes

Pretable's theming surface has three axes that can change at runtime, and all three resolve the same way the toggle above does: set an attribute, let CSS resolve it, no JavaScript touches a token value.

• Theme — pick pretable.css (the default), excel.css, or material.css at build time by importing one. Switch between themes by swapping which CSS file is active (or by setting CSS variables manually if you want a hybrid).
• Density — toggle data-density="compact", data-density="standard", or data-density="spacious" on <html>, or on a wrapper element to scope a region, to switch row heights, padding, and font sizes. The engine notices via a MutationObserver, re-reads the new heights from CSS against the grid's own element, and re-renders. See Density switching for a walkthrough of all three tiers.
• Light / dark — the axis the demo above exercises. Toggle data-theme="dark" on <html> to activate the active theme's dark variant. pretable and Material both ship one; Excel is light-only by design.

All three compose. <html data-theme="dark" data-density="spacious"> gives you the active theme's dark colors at its spacious dimensions. There is nothing for the cascade to resolve between the two attribute blocks: in every theme that ships both, they write disjoint sets of tokens — one appearance, one dimensions — so neither can win or lose against the other. No JavaScript touches the token values; you toggle the attributes and CSS does the rest.

Selection is cell-range first

Pretable's selection model is a list of {startRowId, endRowId, startColumnId, endColumnId} ranges plus an anchor — Excel/Sheets semantics, not a "selected row id" boolean. Row selection is derived from the range model: a row is fully selected when every one of its cells sits inside some range. The built-in three-state checkbox column reads that derivation and writes back via full-row ranges, so cell-range gestures and checkbox clicks share one source of truth. The grid below makes both halves of that model visible at once — a caption underneath echoes the active ranges as you shift-click, Cmd/Ctrl-click, and drag, and the built-in checkbox column derives its three states from exactly the same ranges:

"use client";

import { useState } from "react";

import { PretableSurface } from "@pretable/react";
import type {
  PretableCellRangeFor,
  PretableSelectionFor,
} from "@pretable/react";

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

const VIEWPORT_HEIGHT = 300;

// Echoes `PretableCellRangeFor`'s own fields — the shape the page's
// "Selection model" section describes below — rather than a re-derived summary,
// so the caption stays an honest window onto the controlled state above it.
// Narrowed to `typeof columns`, so a typo'd column id here is a compile error
// rather than a silently-dead comparison.
function describeRange(range: PretableCellRangeFor<typeof columns>): string {
  return range.startRowId === range.endRowId &&
    range.startColumnId === range.endColumnId
    ? `${range.startColumnId}@${range.startRowId}`
    : `${range.startColumnId}@${range.startRowId} → ${range.endColumnId}@${range.endRowId}`;
}

export function RangeSelectionGrid() {
  // The CELL-RANGE slice. Controlled, and narrowed to the column tuple.
  const [selection, setSelection] = useState<
    PretableSelectionFor<typeof columns>
  >({
    ranges: [],
    anchor: null,
  });
  // The CHECKBOX slice, which is a different thing entirely: it lives in the
  // engine, is reported by its own callback, and never appears in `selection`.
  // Wiring only `onSelectionChange` — the mistake this example exists to make
  // hard — leaves the checkboxes ticking with nothing downstream ever hearing.
  const [checkedRowIds, setCheckedRowIds] = useState<readonly string[]>([]);

  return (
    <div>
      <p style={{ margin: "0 0 8px", fontSize: 13 }}>
        Click a cell, then <kbd>Shift</kbd>+click another to extend the range.{" "}
        <kbd>Cmd</kbd>/<kbd>Ctrl</kbd>+click adds a discontiguous range. Drag
        from one cell to another for a marquee selection. Then tick a checkbox,
        and watch the second caption move instead of the first.
      </p>
      <PretableSurface
        ariaLabel="Selection demo"
        columns={columns}
        getRowId={(row) => row.id}
        rows={rows}
        rowSelectionColumn={{ enabled: true }}
        state={{ selection }}
        onSelectionChange={setSelection}
        onRowSelectionChange={setCheckedRowIds}
        viewportHeight={VIEWPORT_HEIGHT}
      />
      <p style={{ margin: "8px 0 0", fontSize: 13 }}>
        Cell ranges (<code>onSelectionChange</code>):{" "}
        <code>
          {selection.ranges.length > 0
            ? selection.ranges.map(describeRange).join(" · ")
            : "(none)"}
        </code>
      </p>
      <p style={{ margin: "4px 0 0", fontSize: 13 }}>
        Ticked rows (<code>onRowSelectionChange</code>):{" "}
        <code>
          {checkedRowIds.length > 0 ? checkedRowIds.join(", ") : "(none)"}
        </code>
      </p>
    </div>
  );
}

Because ranges reference rows and columns by stable id (not index), selection survives sort, filter, and column reorder. Each slice of engine state — sort, filters, selection, focus — is independently controllable: pass the slice to take ownership, omit it to let the engine own it. See Selection for the full model.

Streaming

Pretable can render rows that arrive over the network — JSON streams, transactions API, server-sent events. The streaming pipeline is implemented but the public API is in flux for v0.0.x. See Streaming Overview for the current state.

Pre-1.0 caveat

Pretable ships at version 0.0.x. Token names in @pretable/ui may rename or remove in any patch release. The engine API in @pretable/react is more stable but not frozen. Check the changelog before upgrading.

Where to go next

• Theming Overview — the customization surface, in detail.
• Override tokens — change individual --pretable-* values without forking a theme.
• Token reference — the canonical list of all 50 tokens.

For the architectural rationale (why CSS variables, why density-coupled-to-theme, etc.), the design spec at docs/superpowers/specs/2026-05-02-pretable-docs-architecture-design.md has the why behind the what.