On this page
Advanced framework adapter props for workbook data or datasource ownership.
rowBridgeonRowDeltaonMutationRejectedonRendererFallbackonDatasourceErroronExportErroronReadyclassNamestylefallbackheightfillonGridChangeonSelectionChangeworkbookdatadatasourcedatasourceStoragerendererworkerUrlpresentationthemereadOnlyhyperlinkActivationprotectionResolvermutationPolicytransactionResourceLimitsrendererseditorsoverscanminColumnsconfigonViewportChangeonEditBeginonEditCommitonSearchonActiveSheetChangeonCommandStateChangeonInitializationErrorwasmSource
Members 40
rowBridge Projects canonical changes to host-owned row identities.
onRowDelta Receives one accepted or reconciled row projection.
onMutationRejected Receives structured issues when a Grid mutation is rejected.
onRendererFallback Fires when worker rendering falls back to the main-thread canvas renderer.
onDatasourceError Receives failed datasource requests and their errors.
onExportError Receives failures from built-in XLSX export actions.
onReady Fires after the adapter publishes a ready Grid generation.
className Additional class appended to the required sheetwrite host class.
style Host styles merged before adapter sizing styles.
fallback Content shown while WASM is loading or after initialization fails.
height Host height in CSS pixels for numbers or any CSS length string. height ?: number | string;
fill Fills the parent's available width and height, taking precedence over height.
onGridChange Receives every committed Grid change, including its applied transaction.
onSelectionChange Receives the current selection, or null after it is cleared. onSelectionChange ?: ( selection : Selection | null ) => void ;
workbook Live workbook schema adopted by the store and updated by document operations.
data Eager column-major values loaded into workbook.activeSheet; use instead of datasource.
datasource Lazy row provider requested for visible windows; use instead of eager data.
datasourceStorage Allocation and cache policy for datasource-backed cell storage.
renderer Paint backend; defaults to main-thread canvas and falls back there if a worker fails. renderer ?: "canvas" | "worker" ;
workerUrl URL of the worker renderer module (renderer: "worker"), as served to the BROWSER — the platform Worker constructor does not consult package exports, so a bare specifier like new URL("@sheetwrite/core/worker",… workerUrl ?: string | URL ;
URL of the worker renderer module (`renderer: "worker"`), as served to the
BROWSER — the platform `Worker` constructor does not consult package
exports, so a bare specifier like `new URL("@sheetwrite/core/worker",
import.meta.url)` is NOT reliable. Either copy
`@sheetwrite/core/dist/worker.js` to your public assets and pass its URL
string (works everywhere), or use your bundler's dependency-worker import
if it has one (see `/docs/guides/worker-rendering/`). If omitted or the worker
can't be constructed, the grid falls back to the main-thread canvas
renderer and emits `renderer-fallback` once.
presentation Header presentation. Spreadsheet mode (default) paints positional A/B/C labels; data-grid mode paints each column's semantic header. Header presentation. Spreadsheet mode (default) paints positional A/B/C
labels; data-grid mode paints each column's semantic `header`. Cell
addressing, row indices, clipboard values, formulas, and exports are
unchanged in both modes.
theme Overrides merged over the default theme and host CSS custom properties.
readOnly Disables mutating interactions while preserving navigation and selection.
hyperlinkActivation Hyperlink activation never opens a browser URL. hyperlinkActivation ?: "event-only" | "internal-navigation" | "disabled" ;
Hyperlink activation never opens a browser URL. `event-only` (default)
emits a safe resolved target; `internal-navigation` additionally moves to
stable internal destinations; `disabled` rejects every activation request.
protectionResolver Host-owned client UX permission check. Host-owned client UX permission check. Servers must independently authorize
every submitted operation; this resolver is not an authentication boundary.
mutationPolicy Atomic rejects the transaction; partial skips denied operation objects.
transactionResourceLimits Overrides inclusive operation-count and encoded-byte ceilings for every atomic mutation.
renderers Custom cell renderers registered up front; also see Grid.defineCellRenderer.
editors Named custom editors resolved from each column's editor field.
overscan Extra row and visible-column positions painted on each viewport edge. Extra row and visible-column positions painted on each viewport edge.
Defaults to 6; use 0 to disable the buffer.
minColumns Render at least this many columns, adding empty columns past the data. Render at least this many columns, adding empty columns past the data. A
spreadsheet also adds empty columns to fill the host width; a data grid
adds them only through this option.
config Built-in UI controls; providing an object enables the toolbar unless toolbar is false.
onViewportChange Receives visible row bounds and vertical scroll offset after scrolling. onViewportChange ?: ( event : GridEvents [ "scroll" ]) => void ;
onEditBegin Fires when cell editing begins. onEditBegin ?: ( event : GridEvents [ "edit-begin" ]) => void ;
onEditCommit Fires after an edit commits its parsed cell value. onEditCommit ?: ( event : GridEvents [ "edit-commit" ]) => void ;
onSearch Receives refreshed search matches and active-match index. onSearch ?: ( result : GridEvents [ "search" ]) => void ;
onActiveSheetChange Fires after the visible sheet changes. onActiveSheetChange ?: ( event : GridEvents [ "active-sheet" ]) => void ;
onCommandStateChange Receives observable undo/redo and formatting command state. onCommandStateChange ?: ( event : GridEvents [ "command-state-change" ]) => void ;
onInitializationError Receives a WASM initialization failure while the adapter remains mounted.
wasmSource Explicit source passed to process-wide WASM initialization; concurrent initialization is first-source-wins. wasmSource ?: BufferSource | URL | string | Request | WebAssembly.Module;
Declaration
View full TypeScript declaration
height ?: number | string ;
onSelectionChange ?: ( selection : Selection | null ) => void ; renderer ?: "canvas" | "worker" ;
workerUrl ?: string | URL ;
hyperlinkActivation ?: "event-only" | "internal-navigation" | "disabled" ;
onViewportChange ?: ( event : GridEvents [ "scroll" ]) => void ; onEditBegin ?: ( event : GridEvents [ "edit-begin" ]) => void ; onEditCommit ?: ( event : GridEvents [ "edit-commit" ]) => void ; onSearch ?: ( result : GridEvents [ "search" ]) => void ; onActiveSheetChange ?: ( event : GridEvents [ "active-sheet" ]) => void ; onCommandStateChange ?: ( event : GridEvents [ "command-state-change" ]) => void ; wasmSource ?: BufferSource | URL | string | Request | WebAssembly . Module ;
Referenced by
Workspace packages depending on @sheetwrite/react
@sheetwrite/docs-startdependency
Public exports naming SheetwriteGridProps
class RowBridge {
constructor<
Id extends RowBridgeId = RowBridgeId,
Row extends Record<string, CellScalar> = Record<
string,
CellScalar
>,
>(options: RowBridgeOptions<Row, Id>);
columnKeys: (sheet?: SheetId) => readonly string[];
project: (
event: ChangeEvent,
requestedOperations?: readonly DocumentOp[],
transactionId?: string,
) => RowBridgeProjection<Id>;
reconcile: (
// … 4 more lines — see the API reference
} class RowBridge { constructor < Id extends RowBridgeId = RowBridgeId , Row extends Record < string , CellScalar > = Record < string , CellScalar >, >( options : RowBridgeOptions < Row , Id >); columnKeys : ( sheet ?: SheetId ) => readonly string []; project : ( event : ChangeEvent , requestedOperations ?: readonly DocumentOp [], transactionId ?: string , ) => RowBridgeProjection < Id >; reconcile : ( // … 4 more lines — see the API reference } class RowBridge { constructor < Id extends RowBridgeId = RowBridgeId , Row extends Record < string , CellScalar > = Record < string , CellScalar >, >( options : RowBridgeOptions < Row , Id >, ); columnKeys : ( sheet ?: SheetId , // … 13 more lines — see the API reference } Projects canonical document transactions into host-owned row changes. The bridge only owns compact data-space identity arrays. It never writes to defaultRows, never renders, and never creates a second document store. API reference → type RowBridgeHandler<Id extends RowBridgeId = RowBridgeId> = (
projection: RowBridgeProjection<Id>,
) => void; type RowBridgeHandler < Id extends RowBridgeId = RowBridgeId > = ( projection : RowBridgeProjection < Id >, ) => void ; type RowBridgeHandler < Id extends RowBridgeId = RowBridgeId , > = ( projection : RowBridgeProjection < Id >, ) => void ; Callback accepted by imperative and framework adapters. API reference → interface GridAdapterEventHandlers<
Id extends RowBridgeId = RowBridgeId,
> {
onGridChange?: (event: ChangeEvent) => void;
onRowDelta?: RowBridgeHandler<Id>;
onSelectionChange?: (selection: Selection | null) => void;
onViewportChange?: (event: GridEvents["scroll"]) => void;
onEditBegin?: (event: GridEvents["edit-begin"]) => void;
onEditCommit?: (event: GridEvents["edit-commit"]) => void;
onSearch?: (result: GridEvents["search"]) => void;
onActiveSheetChange?: (event: GridEvents["active-sheet"]) => void;
onCommandStateChange?: (
event: GridEvents["command-state-change"],
) => void;
onMutationRejected?: (
// … 12 more lines — see the API reference
} interface GridAdapterEventHandlers < Id extends RowBridgeId = RowBridgeId , > { onGridChange ?: ( event : ChangeEvent ) => void ; onRowDelta ?: RowBridgeHandler < Id >; onSelectionChange ?: ( selection : Selection | null ) => void ; onViewportChange ?: ( event : GridEvents [ "scroll" ]) => void ; onEditBegin ?: ( event : GridEvents [ "edit-begin" ]) => void ; onEditCommit ?: ( event : GridEvents [ "edit-commit" ]) => void ; onSearch ?: ( result : GridEvents [ "search" ]) => void ; onActiveSheetChange ?: ( event : GridEvents [ "active-sheet" ]) => void ; onCommandStateChange ?: ( event : GridEvents [ "command-state-change" ], ) => void ; onMutationRejected ?: ( // … 12 more lines — see the API reference } interface GridAdapterEventHandlers < Id extends RowBridgeId = RowBridgeId , > { onGridChange ?: ( event : ChangeEvent , ) => void ; onRowDelta ?: RowBridgeHandler < Id >; onSelectionChange ?: ( selection : Selection | null , ) => void ; onViewportChange ?: ( event : GridEvents [ "scroll" ], ) => void ; onEditBegin ?: ( event : GridEvents [ "edit-begin" ], ) => void ; onEditCommit ?: ( event : GridEvents [ "edit-commit" ], // … 29 more lines — see the API reference } Framework-neutral readiness, change, and error callbacks shared by adapters. API reference → interface ChangeEvent {
transaction: Transaction;
changes: CellChange[];
commitReason: CommitReason;
source: OperationSource;
epoch?: number;
} interface ChangeEvent { transaction : Transaction ; changes : CellChange []; commitReason : CommitReason ; source : OperationSource ; epoch ?: number ; } interface ChangeEvent { transaction : Transaction ; changes : CellChange []; commitReason : CommitReason ; source : OperationSource ; epoch ?: number ; } Payload of the change event; flows OUT for API submission/reconcile. API reference → type Selection =
| { kind: "cell"; addr: CellAddress }
| { kind: "range"; range: Range }
| { kind: "row"; sheet: SheetId; row: number }
| { kind: "column"; sheet: SheetId; col: number }
| { kind: "multi"; ranges: Range[] }; type Selection = | { kind : "cell" ; addr : CellAddress } | { kind : "range" ; range : Range } | { kind : "row" ; sheet : SheetId ; row : number } | { kind : "column" ; sheet : SheetId ; col : number } | { kind : "multi" ; ranges : Range [] }; type Selection = | { kind : "cell" ; addr : CellAddress ; } | { kind : "range" ; range : Range ; } | { kind : "row" ; sheet : SheetId ; row : number ; } | { kind : "column" ; sheet : SheetId ; col : number ; } // … 4 more lines — see the API reference } Current cell, range, row, column, or multi-range selection. API reference → interface Workbook {
sheets: Sheet[];
activeSheet: SheetId;
namedRanges?: NamedRangeSnapshot[];
} interface Workbook { sheets : Sheet []; activeSheet : SheetId ; namedRanges ?: NamedRangeSnapshot []; } interface Workbook { sheets : Sheet []; activeSheet : SheetId ; namedRanges ?: NamedRangeSnapshot []; } Live workbook schema containing ordered sheets and the active sheet ID. API reference → interface ColumnarData {
rowCount: number;
columns: Record<string, ArrayLike<CellScalar | CellValue>>;
} interface ColumnarData { rowCount : number ; columns : Record < string , ArrayLike < CellScalar | CellValue >>; } interface ColumnarData { rowCount : number ; columns : Record < string , ArrayLike < CellScalar | CellValue > >; } Eager column-oriented values used to initialize a sheet. API reference → interface DataSource {
readonly capabilities: DataSourceCapabilities;
getRows(request: DataSourceRequest): Promise<DataSourcePage>;
} interface DataSource { readonly capabilities : DataSourceCapabilities ; getRows ( request : DataSourceRequest ) : Promise < DataSourcePage >; } interface DataSource { readonly capabilities : DataSourceCapabilities ; getRows ( request : DataSourceRequest , ) : Promise < DataSourcePage >; } Host callback that asynchronously loads cancellable rectangular pages. @example import type { DataSource, RowData } from "@sheetwrite/core"; const rows: RowData[] = [{ amount: 12 }, { amount: 18 }]; const datasource: DataSource = { capabilities: { protocol: 2, columns: "windowed" }, async getRows(request) { request.signal.throwIfAborted(); return { protocol: 2, start: request.start, columns: request.columns, rows: rows.slice(request.start, request.end).map((row) => Object.fromEntries(request.columns.flatMap((band) => band.keys.map((key) => [key, row[key] ?? null])))), }; }, }; @see GridOptions.datasource @see DataSourceRequest API reference → interface DataSourceStorageOptions {
mode?: "dense" | "paged";
chunkRows?: number;
cacheBytes?: number;
dirtyCellLimit?: number;
} interface DataSourceStorageOptions { mode ?: "dense" | "paged" ; chunkRows ?: number ; cacheBytes ?: number ; dirtyCellLimit ?: number ; } interface DataSourceStorageOptions { mode ?: "dense" | "paged" ; chunkRows ?: number ; cacheBytes ?: number ; dirtyCellLimit ?: number ; } Dense or allocation-lazy paged storage policy for datasource cells. API reference → type GridPresentation = "spreadsheet" | "data-grid"; type GridPresentation = "spreadsheet" | "data-grid" ; type GridPresentation = "spreadsheet" | "data-grid" ; Header semantics used by the retained canvas and accessibility mirror. API reference → interface Theme {
font: string;
bg: string;
fg: string;
gridLine: string;
headerBg: string;
headerFg: string;
selection: string;
selectionBorder: string;
rowHeight: number;
headerHeight: number;
rowHeaderWidth: number;
searchMatch: string;
searchActiveMatch: string;
highlight: string;
} interface Theme { font : string ; bg : string ; fg : string ; gridLine : string ; headerBg : string ; headerFg : string ; selection : string ; selectionBorder : string ; rowHeight : number ; headerHeight : number ; rowHeaderWidth : number ; searchMatch : string ; searchActiveMatch : string ; highlight : string ; } interface Theme { font : string ; bg : string ; fg : string ; gridLine : string ; headerBg : string ; headerFg : string ; selection : string ; selectionBorder : string ; rowHeight : number ; headerHeight : number ; rowHeaderWidth : number ; searchMatch : string ; searchActiveMatch : string ; highlight : string ; } Resolved canvas colors, typography, and geometry used for painting. API reference → type ProtectionResolver = (
request: ProtectionRequest,
) => "allow" | "deny"; type ProtectionResolver = ( request : ProtectionRequest , ) => "allow" | "deny" ; type ProtectionResolver = ( request : ProtectionRequest , ) => "allow" | "deny" ; Host-owned client UX permission callback for protected mutations. API reference → type MutationPolicyMode = "atomic" | "partial"; type MutationPolicyMode = "atomic" | "partial" ; type MutationPolicyMode = "atomic" | "partial" ; Atomic or partial handling for locally denied operations. API reference → interface TransactionResourceLimits {
maxOperations: number;
maxEncodedBytes: number;
} interface TransactionResourceLimits { maxOperations : number ; maxEncodedBytes : number ; } interface TransactionResourceLimits { maxOperations : number ; maxEncodedBytes : number ; } Public ceilings shared by transaction producers, persistence, transport, and replay. Limits measure the submitted operation array itself, not the logical cell area covered by compact operations. API reference → interface CellRenderer {
canvas?(ctx: CanvasRenderingContext2D, c: CellPaintContext): void;
dom?(c: CellPaintContext): HTMLElement;
update?(element: HTMLElement, c: CellPaintContext): void;
destroy?(element: HTMLElement): void;
} interface CellRenderer { canvas ? ( ctx : CanvasRenderingContext2D , c : CellPaintContext ) : void ; dom ? ( c : CellPaintContext ) : HTMLElement ; update ? ( element : HTMLElement , c : CellPaintContext ) : void ; destroy ? ( element : HTMLElement ) : void ; } interface CellRenderer { canvas ? ( ctx : CanvasRenderingContext2D , c : CellPaintContext , ) : void ; dom ? ( c : CellPaintContext , ) : HTMLElement ; update ? ( element : HTMLElement , c : CellPaintContext , ) : void ; destroy ? ( element : HTMLElement , ) : void ; } Custom cell renderer hooks for the main-thread canvas or retained DOM overlay. API reference → interface CellEditor {
mount(
host: HTMLElement,
context: CellEditorContext,
): CellEditorInstance;
} interface CellEditor { mount ( host : HTMLElement , context : CellEditorContext , ) : CellEditorInstance ; } interface CellEditor { mount ( host : HTMLElement , context : CellEditorContext , ) : CellEditorInstance ; } Framework-neutral named editor definition registered through GridOptions.editors. API reference → interface GridConfig {
toolbar?: boolean | ToolbarItem[];
bold?: boolean;
italic?: boolean;
align?: boolean;
textColor?: boolean;
fillColor?: boolean;
border?: boolean;
clearFormat?: boolean;
merge?: boolean;
sort?: boolean;
export?: boolean;
icons?: Partial<Record<ToolbarActionName, ToolbarIcon>>;
contextMenu?: boolean | ContextMenuItems;
undo?: boolean;
// … 7 more lines — see the API reference
} interface GridConfig { toolbar ?: boolean | ToolbarItem []; bold ?: boolean ; italic ?: boolean ; align ?: boolean ; textColor ?: boolean ; fillColor ?: boolean ; border ?: boolean ; clearFormat ?: boolean ; merge ?: boolean ; sort ?: boolean ; export ?: boolean ; icons ?: Partial < Record < ToolbarActionName , ToolbarIcon >>; contextMenu ?: boolean | ContextMenuItems ; undo ?: boolean ; // … 7 more lines — see the API reference } interface GridConfig { toolbar ?: boolean | ToolbarItem []; bold ?: boolean ; italic ?: boolean ; align ?: boolean ; textColor ?: boolean ; fillColor ?: boolean ; border ?: boolean ; clearFormat ?: boolean ; merge ?: boolean ; sort ?: boolean ; export ?: boolean ; icons ?: Partial < Record < ToolbarActionName , ToolbarIcon > >; // … 13 more lines — see the API reference } Toolbar / feature configuration. When config is set the built-in toolbar is shown; control flags default to true except the opt-in export flag. @example import type { GridConfig } from "@sheetwrite/core"; const config: GridConfig = { toolbar: true, contextMenu: [{ action: "copy" }, { action: "paste" }], keyboard(event, grid) { if (event.altKey && event.key === "b") { grid.actions.toggleBold(); return true; } return false; }, }; @see Grid.setConfig @see ContextMenuItem API reference → interface GridEvents {
change: ChangeEvent;
selection: { selection: Selection | null };
scroll: {
scrollTop: number;
firstRow: number;
lastRow: number;
scrollLeft: number;
firstVisibleColumn: number | null;
lastVisibleColumn: number | null;
};
"edit-begin": { addr: CellAddress };
"edit-commit": { addr: CellAddress; value: CellValue };
search: SearchResult;
"command-state-change": GridCommandStateChangeEvent;
// … 17 more lines — see the API reference
} interface GridEvents { change : ChangeEvent ; selection : { selection : Selection | null }; scroll : { scrollTop : number ; firstRow : number ; lastRow : number ; scrollLeft : number ; firstVisibleColumn : number | null ; lastVisibleColumn : number | null ; }; "edit-begin" : { addr : CellAddress }; "edit-commit" : { addr : CellAddress ; value : CellValue }; search : SearchResult ; "command-state-change" : GridCommandStateChangeEvent ; // … 17 more lines — see the API reference } interface GridEvents { change : ChangeEvent ; selection : { selection : Selection | null ; }; scroll : { scrollTop : number ; firstRow : number ; lastRow : number ; scrollLeft : number ; firstVisibleColumn : number | null ; lastVisibleColumn : number | null ; }; "edit-begin" : { addr : CellAddress ; }; "edit-commit" : { // … 31 more lines — see the API reference } Payload map for events emitted by a Grid. API reference → class SheetwriteError
extends Error
implements SheetwriteErrorEnvelope
{
constructor(
code: SheetwriteErrorCode,
operation: SheetwriteErrorOperation,
message: string,
options?: SheetwriteErrorOptions,
);
code:
| "aborted"
| "batch-limit"
| "blocked"
| "buffer-byte-limit"
// … 78 more lines — see the API reference
} class SheetwriteError extends Error implements SheetwriteErrorEnvelope { constructor ( code : SheetwriteErrorCode , operation : SheetwriteErrorOperation , message : string , options ?: SheetwriteErrorOptions , ); code : | "aborted" | "batch-limit" | "blocked" | "buffer-byte-limit" // … 78 more lines — see the API reference } class SheetwriteError extends Error implements SheetwriteErrorEnvelope { constructor ( code : SheetwriteErrorCode , operation : SheetwriteErrorOperation , message : string , options ?: SheetwriteErrorOptions , ); code : | "aborted" | "batch-limit" | "blocked" | "buffer-byte-limit" | "buffer-count-limit" | "buffer-operation-limit" | "comment-failed" // … 80 more lines — see the API reference } Canonical envelope for thrown and callback-delivered Sheetwrite failures. API reference → type RowBridgeId = string | number; type RowBridgeId = string | number ; type RowBridgeId = string | number ; A stable host identity for one data-space row. API reference →