Grid The Pretable component

The Pretable component

The concise declarative Pretable preset.

<Pretable> is the shortest path to a grid. Pass typed rows and columns; it uses the same indexed local row model as <PretableSurface>.

A library catalog, three props of columns

Five books rendered with createColumnHelper and the Pretable preset — no sort UI, no filter UI, no controlled state, just typed columns and rows.

.md

That's the complete recipe — createColumnHelper plus as const for a typed column tuple, then rows, columns, ariaLabel, and getRowId:

People.tsx
import { createColumnHelper } from "@pretable/core";
import { Pretable } from "@pretable/react";
 
interface Person {
  id: string;
  name: string;
  city: string;
}
 
const column = createColumnHelper<Person>();
const columns = [
  column.accessor("name", { type: "text", header: "Name" }),
  column.accessor("city", { type: "text", header: "City" }),
] as const;
 
export function People({ rows }: { rows: Person[] }) {
  return (
    <Pretable
      rows={rows}
      columns={columns}
      ariaLabel="People directory"
      getRowId={(row) => row.id}
    />
  );
}

Row identity is never derived from array position. Person above has a conventional id, so getRowId is optional there and the grid reads row.id; the example passes it anyway to name the key explicitly. For a row whose stable key is anything else, getRowId is required and omitting it is a type error, not a runtime surprise.

Props

columns, rows, and ariaLabel are required, and so is getRowId unless the row has a conventional string or number id — ariaLabel is the grid's accessible name, so give it something a screen reader user would recognize as this table's contents (e.g. "People directory", not a generic placeholder). The concise preset also forwards row activation and selection callbacks, row changes, clipboard hooks, tab behavior, messages, the optional selection column, and column width/order/pinning callbacks. Use <PretableSurface> for controlled query and interaction state, grouping controls, custom renderers, explicit row-model ownership, telemetry, or a custom viewport height.

Server-side data

The preset forwards the server-data props verbatim: processing declares which of filtering and sorting the caller applies rather than the engine, resultMeta carries the matching total and the dataset identity, and dataState names the lifecycle phase the request is in. onQueryChange reports the query the engine now holds — <Pretable> never accepts query, so this is the observed shape rather than a controlled one, and owning the reader's intent still means reaching for <PretableSurface>.

renderBodyState is not among them. Consumer-owned loading, empty, and error bodies belong to <PretableSurface>; the preset renders the built-in ones. See Server-side data for what each prop obliges you to supply.

Defaults

<Pretable> wraps the surface with these defaults:

  • Viewport height: 320px.
  • Cell rendering: the plain formatted value — no built-in label or wrapper.
  • Header rendering: column label plus a sort-direction glyph once a column is sorted.
  • Indexed rows ownership: rows are reconciled into one long-lived local row model.
  • No controlled query or filter UI: use <PretableSurface> when application code must own those behaviors.

Theming

css
@import "@pretable/ui/themes/pretable.css";
@import "@pretable/ui/grid.css";

The grid uses the active theme's surface tones, gridlines, semantic colors, and density tokens. Toggle data-density on <html>, or on a wrapper element to scope one region, to switch compact, standard, or spacious tiers. See Theming overview for the complete model.

Limitations

The preset intentionally does not expose a custom viewport height, filter or grouping UI, controlled state, telemetry, custom cell/header components, or explicit row-model mode. Those belong to <PretableSurface>. Drop to the headless engine only when you also need to own rendering.

One piece of configuration UI ships on by default: the tool panel, the rail at the grid's right edge whose Columns section hides, pins, and reorders columns, whose Filters section builds the query's filter tree, and whose Grouping section manages the group-by levels, expansion, and aggregates. The preset forwards toolPanel verbatim — pass toolPanel={false} to remove it, or a PretableToolPanelConfig to control which section is open.

Where to go next