Grid options and presentation

Everything you pass to createGrid(host, opts) is a GridOptions field.

const grid = createGrid(host, {
  workbook,
  data,
  presentation: "data-grid",
  overscan: 4,
});

import {
  createGrid,
  initSheetwrite,
  type ColumnarData,
  type Workbook,
} from "@sheetwrite/core";
import "@sheetwrite/core/styles.css";

const host = document.querySelector<HTMLElement>("#grid");
if (host === null) throw new Error("Missing #grid host");
host.style.height = "320px";

const workbook: Workbook = {
  activeSheet: "people",
  sheets: [
    {
      id: "people",
      name: "People",
      rowCount: 2,
      columns: [
        { key: "name", header: "Customer name", width: 220, type: "text" },
        { key: "status", header: "Account status", width: 160, type: "text" },
      ],
    },
  ],
};
const data: ColumnarData = {
  rowCount: 2,
  columns: { name: ["Ada", "Grace"], status: ["Active", "Paused"] },
};

await initSheetwrite();
const grid = createGrid(host, { workbook, data, presentation: "data-grid", overscan: 4 });
console.log(grid.store.getCell({ sheet: "people", row: 0, col: 0 }).resolved); // "Ada"

The header band shows "Customer name" and "Account status" instead of A and B. Row 0 still holds the first data row.

GridOptions

type CreateGrid = (host: HTMLElement, opts: GridOptions) => Grid;

Spreadsheet and data-grid presentation

presentation: "spreadsheet" is the backward-compatible default. It paints and announces positional column headers (A, B, C, …). Use presentation: "data-grid" when the columns describe row-object fields:

const workbook: Workbook = {
  activeSheet: "people",
  sheets: [{
    id: "people",
    name: "People",
    rowCount: people.length,
    columns: [
      { key: "name", header: "Customer name", width: 220, type: "text" },
      { key: "status", header: "Account status", width: 160, type: "text" },
    ],
  }],
};

const grid = createGrid(host, {
  workbook,
  data,
  presentation: "data-grid",
});

The semantic header occupies the same header band as A/B/C; it does not consume row 0. These keep their zero-based data coordinates:

• cell addresses, formulas, selections and row numbers
• clipboard payloads and CSV/XLSX schema labels
• mutation events and datasource ranges

Table exports use Column.header in both presentation modes. The data-first Sheetwrite components select "data-grid" automatically because every SimpleColumn requires a title.

Custom cell renderers

A CellRenderer paints or retains a DOM node for each cell in the rendered window. Register it in renderers or later with grid.defineCellRenderer(name, renderer). When dom is present, it owns the cell content. The canvas still paints the cell background, border, headers, and grid lines.

interface CellRenderer {
  canvas?(ctx: CanvasRenderingContext2D, c: CellPaintContext): void;
  dom?(c: CellPaintContext): HTMLElement;
  update?(element: HTMLElement, c: CellPaintContext): void;
  destroy?(element: HTMLElement): void;
}

A legacy renderer with only dom is recreated when its value, style, theme, or size changes, but not for a pure scroll.

DOM cells are clipped to the viewport and frozen pane that owns them. A merged range produces one node for its anchor, not one node per covered cell. Plain renderer output stays hidden from assistive technology because the compact ARIA mirror already exposes its cell value. To make a renderer explicitly interactive:

1. Return a native control, or add a non-negative tabindex.
2. Give it an accessible name.
3. Set element.style.pointerEvents = "auto".

Keyboard events from that control stay with the control instead of moving the grid.

With renderer: "worker", canvas hooks cannot cross the Worker boundary. dom, update, and destroy still run on the main thread in the retained overlay.

Framework adapters

Framework adapters classify every GridOptions field centrally:

Readiness includes the resulting generation and reset reason.

Framework adapters also accept wasmSource. Initialization is process-wide and first-source-wins:

• Concurrent calls that use the same source share one attempt. A different source rejects until that attempt settles.
• If the winning attempt succeeds, every still-mounted adapter becomes ready, even when its prop changed during the attempt.
• A change to wasmSource after readiness warns and keeps the live grid, selection, edits, generation, and ready-event count unchanged.
• A true initialization failure remains observable through onInitializationError, and a later source can retry it.

Edge cases and limits

• Presentation is construction-bound. Changing it through a framework adapter replaces the grid with reason: "input-reset"; it does not rename columns or move data in place.
• Pass data or datasource, not both.
• readOnly keeps navigation and selection. Only mutating interactions stop.
• protectionResolver is client-side UX policy. Your server must still authorize every submitted operation.

See also

• Custom editors
• Toolbar and ribbon
• Grid methods
• Framework lifecycle
• Generated GridOptions and CellRenderer contracts