Adapter lifecycle — Sheetwrite

Every adapter follows one lifecycle:

mount the framework component;
initialize the shared WASM runtime;
create one Grid generation;
publish readiness;
reset only when structural ownership changes;
destroy the generation on unmount.

Pick a framework in any tab group below; the selection is remembered and reused across documentation pages.

Pick the ownership model

Use Sheetwrite for a data-first, uncontrolled grid: pass columns plus initial rows and let the component own the live document.

Use SheetwriteGrid for an advanced Workbook plus eager data or a datasource. It exposes the imperative Grid after readiness and keeps structural configuration under the host's control.

The imperative core has one ownership mode: the host supplies the workbook and data, awaits runtime initialization, and destroys the returned grid.

import { createGridfunction createGrid(host: HTMLElement, opts: GridOptions): Gridfunction createGrid(
  host: HTMLElement,
  opts: GridOptions,
): Gridfunction createGrid(
  host: HTMLElement,
  opts: GridOptions,
): GridCreates and mounts an imperative Grid in the supplied host element.API reference →, initSheetwritefunction initSheetwrite(source?: BufferSource | URL | string | Request | WebAssembly.Module): Promise<void>function initSheetwrite(
  source?:
    BufferSource | URL | string | Request | WebAssembly.Module,
): Promise<void>function initSheetwrite(
  source?:
    | BufferSource
    | URL
    | string
    | Request
    | WebAssembly.Module,
): Promise<void>Load the WASM data engine once. Must be awaited before createGrid.API reference → } from "@sheetwrite/core";

await initSheetwritefunction initSheetwrite(source?: BufferSource | URL | string | Request | WebAssembly.Module): Promise<void>function initSheetwrite(
  source?:
    BufferSource | URL | string | Request | WebAssembly.Module,
): Promise<void>function initSheetwrite(
  source?:
    | BufferSource
    | URL
    | string
    | Request
    | WebAssembly.Module,
): Promise<void>Load the WASM data engine once. Must be awaited before createGrid.API reference →();
const gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference → = createGridfunction createGrid(host: HTMLElement, opts: GridOptions): Gridfunction createGrid(
  host: HTMLElement,
  opts: GridOptions,
): Gridfunction createGrid(
  host: HTMLElement,
  opts: GridOptions,
): GridCreates and mounts an imperative Grid in the supplied host element.API reference →(hostconst host: HTMLElementconst host: HTMLElementconst host: HTMLElement, { workbookGridOptions.workbook: Workbookinterface GridOptions {
  workbook: Workbook;
}interface GridOptions {
  workbook: Workbook;
}Live workbook schema adopted by the store and updated by document operations.API reference →, dataGridOptions.data?: ColumnarData | undefinedinterface GridOptions {
  data?: ColumnarData | undefined;
}interface GridOptions {
  data?: ColumnarData | undefined;
}Eager column-major values loaded into workbook.activeSheet; use instead of datasource.API reference → });

// Later, when the host DOM lifetime ends:
gridconst grid: Gridconst grid: Gridconst grid: GridThe imperative core grid this controller owns.API reference →.destroyGrid.destroy(): voidGrid.destroy(): voidGrid.destroy(): voidDetach every event subscription and destroy the grid. Call exactly once.API reference →();

<Sheetwriteconst Sheetwrite: <Row extends Record<string, CellScalar>>(props: SheetwriteProps<Row> & {
    ref?: ForwardedRef<Grid>;
}) => ReactElementconst Sheetwrite: <Row extends Record<string, CellScalar>>(
  props: SheetwriteProps<Row> & {
    ref?: ForwardedRef<Grid>;
  },
) => ReactElementconst Sheetwrite: <
  Row extends Record<
    string,
    CellScalar
  >,
>(
  props: SheetwriteProps<Row> & {
    ref?: ForwardedRef<Grid>;
  },
) => ReactElementConvenience component for local object rows. It derives a single-sheet workbook from columns, defaultRows, and sheetName, initializes Sheetwrite, and owns the Grid through prop-driven resets and unmount cleanup. Pass a ref to access the live Grid; use SheetwriteGrid when the host already owns a workbook or datasource.API reference →
  columnscolumns: readonly SimpleColumn<Record<string, CellScalar>>[]let columns: readonly SimpleColumn<
  Record<string, CellScalar>
>[]let columns: readonly SimpleColumn<
  Record<string, CellScalar>
>[]Ordered schema used to derive the component-owned sheet.API reference →={columnsconst columns: readonly SimpleColumn<Record<string, CellScalar>>[]const columns: readonly SimpleColumn<
  Record<string, CellScalar>
>[]const columns: readonly SimpleColumn<
  Record<string, CellScalar>
>[]Restrict to these column indices (defaults to all columns).API reference →}
  defaultRowsdefaultRows: readonly Record<string, CellScalar>[]let defaultRows: readonly Record<string, CellScalar>[]let defaultRows: readonly Record<
  string,
  CellScalar
>[]Rows converted to initial columnar data; missing column keys become null.API reference →={rowsconst rows: readonly Record<string, CellScalar>[]const rows: readonly Record<string, CellScalar>[]const rows: readonly Record<
  string,
  CellScalar
>[]end-exclusive row rangeAPI reference →}
  onGridChangeonGridChange?: ((event: ChangeEvent) => void) | undefinedonGridChange?: ((event: ChangeEvent) => void) | undefinedonGridChange?: ((event: ChangeEvent) => void) | undefinedReceives every committed Grid change, including its applied transaction.API reference →={persistconst persist: (transaction: Transaction) => voidconst persist: (transaction: Transaction) => voidconst persist: (
  transaction: Transaction,
) => void}
  onReadyonReady?: ((event: GridReadyEvent) => void) | undefinedonReady?: ((event: GridReadyEvent) => void) | undefinedonReady?: ((event: GridReadyEvent) => void) | undefinedFires after the adapter publishes a ready Grid generation.API reference →={({ gridgrid: Gridlet grid: Gridlet grid: GridLive handle just published by the adapter; replaced on the next reset generation.API reference →, generationgeneration: numberlet generation: numberlet generation: numberOne-based adapter generation, incremented whenever a Grid is replaced.API reference →, reasonreason: GridReadyReasonlet reason: GridReadyReasonlet reason: GridReadyReasonWhether readiness followed first initialization, an input reset, or a renderer reset.API reference → }) => observeconst observe: (grid: Grid, generation: number, reason: string) => voidconst observe: (
  grid: Grid,
  generation: number,
  reason: string,
) => voidconst observe: (
  grid: Grid,
  generation: number,
  reason: string,
) => void(gridgrid: Gridlet grid: Gridlet grid: GridLive handle just published by the adapter; replaced on the next reset generation.API reference →, generationgeneration: numberlet generation: numberlet generation: numberOne-based adapter generation, incremented whenever a Grid is replaced.API reference →, reasonreason: GridReadyReasonlet reason: GridReadyReasonlet reason: GridReadyReasonWhether readiness followed first initialization, an input reset, or a renderer reset.API reference →)}
/>

<SheetwriteGridconst SheetwriteGrid: ForwardRefExoticComponent<SheetwriteGridProps & RefAttributes<Grid>>const SheetwriteGrid: ForwardRefExoticComponent<
  SheetwriteGridProps & RefAttributes<Grid>
>const SheetwriteGrid: ForwardRefExoticComponent<
  SheetwriteGridProps &
    RefAttributes<Grid>
>Advanced framework component for workbook data or datasource input.API reference →
  refRefAttributes<Grid>.ref?: Ref<Grid> | undefinedinterface RefAttributes<Grid> {
  ref?: Ref<Grid> | undefined;
}interface RefAttributes<Grid> {
  ref?: Ref<Grid> | undefined;
}Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref).@see {@link react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}={gridRefconst gridRef: Grid | nullconst gridRef: Grid | nullconst gridRef: Grid | null}
  workbookGridOptions.workbook: Workbookinterface GridOptions {
  workbook: Workbook;
}interface GridOptions {
  workbook: Workbook;
}Live workbook schema adopted by the store and updated by document operations.API reference →={workbookconst workbook: Workbookconst workbook: Workbookconst workbook: WorkbookLive workbook schema adopted by the store and updated by document operations.API reference →}
  datasourceGridOptions.datasource?: DataSource | undefinedinterface GridOptions {
  datasource?: DataSource | undefined;
}interface GridOptions {
  datasource?:
    DataSource | undefined;
}Lazy row provider requested for visible windows; use instead of eager data.API reference →={datasourceconst datasource: DataSourceconst datasource: DataSourceconst datasource: DataSourceLazy row provider requested for visible windows; use instead of eager data.API reference →}
  onReadyGridAdapterEventHandlers.onReady?: ((event: GridReadyEvent) => void) | undefinedinterface GridAdapterEventHandlers {
  onReady?: ((event: GridReadyEvent) => void) | undefined;
}interface GridAdapterEventHandlers {
  onReady?:
    | ((
        event: GridReadyEvent,
      ) => void)
    | undefined;
}Fires after the adapter publishes a ready Grid generation.API reference →={({ gridgrid: Gridlet grid: Gridlet grid: GridLive handle just published by the adapter; replaced on the next reset generation.API reference → }) => connectconst connect: (grid: Grid) => voidconst connect: (grid: Grid) => voidconst connect: (
  grid: Grid,
) => void(gridgrid: Gridlet grid: Gridlet grid: GridLive handle just published by the adapter; replaced on the next reset generation.API reference →)}
/>

defaultRows is seed data. Changing it after mount does not replace committed edits; a new columns, defaultRows, or sheetName identity derives a new document and creates a new generation.

<Sheetwrite
  :columns="columns"
  :default-rows="rows"
  @grid-change="persist"
  @ready="({ grid, generation, reason }) => observe(grid, generation, reason)"
/>

<SheetwriteGrid
  ref="gridComponent"
  :workbook="workbook"
  :datasource="datasource"
  @ready="({ grid }) => connect(grid)"
/>

The template ref exposes { grid } after readiness. defaultRows seeds the document once; a new columns, defaultRows, or sheetName identity creates a new generation.

<script lang="ts">
  import type { GridReadyEventinterface GridReadyEventinterface GridReadyEventinterface GridReadyEventGrid handle, generation, and reason published after adapter initialization.API reference → } from "@sheetwrite/core/adapter";
  const handleReadyconst handleReady: ({ grid, generation, reason }: GridReadyEvent) => voidconst handleReady: ({
  grid,
  generation,
  reason,
}: GridReadyEvent) => voidconst handleReady: ({
  grid,
  generation,
  reason,
}: GridReadyEvent) => void = ({ gridgrid: Gridlet grid: Gridlet grid: GridLive handle just published by the adapter; replaced on the next reset generation.API reference →, generationgeneration: numberlet generation: numberlet generation: numberOne-based adapter generation, incremented whenever a Grid is replaced.API reference →, reasonreason: GridReadyReasonlet reason: GridReadyReasonlet reason: GridReadyReasonWhether readiness followed first initialization, an input reset, or a renderer reset.API reference → }: GridReadyEventinterface GridReadyEventinterface GridReadyEventinterface GridReadyEventGrid handle, generation, and reason published after adapter initialization.API reference →) =>
    observeconst observe: (grid: Grid, generation: number, reason: string) => voidconst observe: (
  grid: Grid,
  generation: number,
  reason: string,
) => voidconst observe: (
  grid: Grid,
  generation: number,
  reason: string,
) => void(gridgrid: Gridlet grid: Gridlet grid: GridLive handle just published by the adapter; replaced on the next reset generation.API reference →, generationgeneration: numberlet generation: numberlet generation: numberOne-based adapter generation, incremented whenever a Grid is replaced.API reference →, reasonreason: GridReadyReasonlet reason: GridReadyReasonlet reason: GridReadyReasonWhether readiness followed first initialization, an input reset, or a renderer reset.API reference →);
</script>

<Sheetwriteconst Sheetwrite: Component<SheetwriteProps<Record<string, CellScalar>>, {}, "grid">const Sheetwrite: Component<
  SheetwriteProps<Record<string, CellScalar>>,
  {},
  "grid"
>const Sheetwrite: Component<
  SheetwriteProps<
    Record<string, CellScalar>
  >,
  {},
  "grid"
>Owns a sheet derived from columns and defaultRows. Bind grid for imperative access; it clears on reset or unmount.API reference → {columnscolumns: readonly SimpleColumn<Record<string, CellScalar>>[]let columns: readonly SimpleColumn<
  Record<string, CellScalar>
>[]let columns: readonly SimpleColumn<
  Record<string, CellScalar>
>[]Restrict to these column indices (defaults to all columns).API reference →} defaultRows={rowsconst rows: readonly Record<string, CellScalar>[]const rows: readonly Record<string, CellScalar>[]const rows: readonly Record<
  string,
  CellScalar
>[]end-exclusive row rangeAPI reference →} onGridChange={persistconst persist: (transaction: Transaction) => voidconst persist: (transaction: Transaction) => voidconst persist: (
  transaction: Transaction,
) => void} onReady={handleReadyconst handleReady: ({ grid, generation, reason }: GridReadyEvent) => voidconst handleReady: ({
  grid,
  generation,
  reason,
}: GridReadyEvent) => voidconst handleReady: ({
  grid,
  generation,
  reason,
}: GridReadyEvent) => void} />

<script lang="ts">
  import type { Gridinterface Gridinterface Gridinterface GridImperative grid handle for document commands, events, rendering, and teardown.API reference → } from "@sheetwrite/core";
  import type { GridReadyEventinterface GridReadyEventinterface GridReadyEventinterface GridReadyEventGrid handle, generation, and reason published after adapter initialization.API reference → } from "@sheetwrite/core/adapter";
  let gridRef: Gridinterface Gridinterface Gridinterface GridImperative grid handle for document commands, events, rendering, and teardown.API reference → | undefined;
  const handleReadyconst handleReady: ({ grid }: GridReadyEvent) => voidconst handleReady: ({ grid }: GridReadyEvent) => voidconst handleReady: ({
  grid,
}: GridReadyEvent) => void = ({ gridgrid: Gridlet grid: Gridlet grid: GridLive handle just published by the adapter; replaced on the next reset generation.API reference → }: GridReadyEventinterface GridReadyEventinterface GridReadyEventinterface GridReadyEventGrid handle, generation, and reason published after adapter initialization.API reference →) => connectconst connect: (grid: Grid) => voidconst connect: (grid: Grid) => voidconst connect: (
  grid: Grid,
) => void(gridgrid: Gridlet grid: Gridlet grid: GridLive handle just published by the adapter; replaced on the next reset generation.API reference →);
</script>

<SheetwriteGridconst SheetwriteGrid: Component<SheetwriteGridProps, {}, "grid">const SheetwriteGrid: Component<
  SheetwriteGridProps,
  {},
  "grid"
>const SheetwriteGrid: Component<
  SheetwriteGridProps,
  {},
  "grid"
>Advanced framework component for workbook data or datasource input.API reference → bind:gridgrid: Grid | nulllet grid: Grid | nulllet grid: Grid | nullLive handle just published by the adapter; replaced on the next reset generation.API reference →={gridRefconst gridRef: Grid | nullconst gridRef: Grid | nullconst gridRef: Grid | null} {workbookworkbook: Workbooklet workbook: Workbooklet workbook: WorkbookLive workbook schema adopted by the store and updated by document operations.API reference →} {datasourcedatasource: DataSourcelet datasource: DataSourcelet datasource: DataSourceLazy row provider requested for visible windows; use instead of eager data.API reference →} onReady={handleReadyconst handleReady: ({ grid }: GridReadyEvent) => voidconst handleReady: ({ grid }: GridReadyEvent) => voidconst handleReady: ({
  grid,
}: GridReadyEvent) => void} />

bind:grid publishes the live handle and clears it on reset or unmount. defaultRows seeds the document once; a new columns, defaultRows, or sheetName identity creates a new generation.

Readiness is generation-scoped

onReady receives { grid, generation, reason }. generation is one-based and increments whenever the adapter replaces its Grid. reason is exactly one of:

"initial" — the first generation after mount and WASM initialization;
"input-reset" — a reset-classified document input changed identity;
"renderer-reset" — renderer, workerUrl, or renderers changed identity.

The exposed handle (React ref, Vue expose, Svelte bind:grid) is assigned before onReady runs and cleared when that generation is destroyed. Reattach subscriptions and collaboration coordinators inside onReady; never retain a stale Grid across a reset.

Controlled values do not reset the document

theme, readOnly, config, overscan, and minColumns are live: changing them updates the current generation in place without recreating the grid or replaying defaultRows. Callbacks and host sizing (height, fill, className/class, style) are also safe to change live.

Structural changes are different. Every reset-classified input is compared by identity:

Change	Result
`workbook`, `data`, `datasource`, `datasourceStorage`	New generation, `reason: "input-reset"`
`protectionResolver`, `mutationPolicy`, `transactionResourceLimits`	New generation, `reason: "input-reset"`
`renderer`, `workerUrl`, `renderers`	New generation, `reason: "renderer-reset"`
`columns`, `defaultRows`, `sheetName` (simple component)	New derived document, `reason: "input-reset"`
`theme`, `readOnly`, `config`, `overscan`, `minColumns`	In-place update, no reset

Keep reset-classified inputs referentially stable (module constants, memoized values, or state) unless you intend to create a new generation.

Transactions and persistence

onGridChange receives committed transactions. transaction.patches is the exhaustive document operation list; changes is the cell-level compatibility view.

function persist(event: ChangeEventinterface ChangeEventinterface ChangeEventinterface ChangeEventPayload of the change event; flows OUT for API submission/reconcile.API reference →): void {
  if (eventevent: ChangeEventlet event: ChangeEventlet event: ChangeEvent.sourceChangeEvent.source: OperationSourceinterface ChangeEvent {
  source: OperationSource;
}interface ChangeEvent {
  source: OperationSource;
}Remote input is observable but never belongs in outgoing local persistence.API reference → === "local") operationQueueconst operationQueue: {
    push(...patches: Transaction["patches"]): void;
}const operationQueue: {
  push(...patches: Transaction["patches"]): void;
}const operationQueue: {
  push(
    ...patches: Transaction["patches"]
  ): void;
}.pushfunction push(...patches: Transaction["patches"]): voidfunction push(...patches: Transaction["patches"]): voidfunction push(
  ...patches: Transaction["patches"]
): void(...eventevent: ChangeEventlet event: ChangeEventlet event: ChangeEvent.transactionChangeEvent.transaction: Transactioninterface ChangeEvent {
  transaction: Transaction;
}interface ChangeEvent {
  transaction: Transaction;
}Operations that actually committed after policy and bounds filtering.API reference →.patchesTransaction.patches: DocumentOp[]interface Transaction {
  patches: DocumentOp[];
}interface Transaction {
  patches: DocumentOp[];
}Ordered document operations submitted as one store commit.API reference →);
}

Use event.reason for audit context, not to reconstruct the transaction. For offline durability and replay, persist operations with SheetwriteStore or your own PersistenceAdapter.

Initialization failures

Framework components surface initialization errors instead of rendering a dead grid. React uses fallback and onInitializationError; Vue and Svelte support fallback content or slots plus their error callback/event.

WASM initialization is process-wide and monotonic: every adapter converges on the same runtime, and when several pass an explicit wasmSource concurrently, the first source wins. While initialization has not yet succeeded, a changed wasmSource or a remount retries it; after the runtime is ready, the source is fixed for the process.

Server rendering

Importing an adapter during SSR is safe, but the grid initializes only after a browser mount. Put it behind the host framework's client boundary:

React/Next.js: a client component;
Nuxt: <ClientOnly>;
SvelteKit: a browser-only branch or client-mounted component.

No framework owns the global runtime. All adapters converge on the same monotonic initializer.