Everything you pass to createGrid(host, opts) lives in GridOptions. This page
lists every field with its type and default, the optional toolbar GridConfig,
and the Grid instance API.
GridOptions
Partial example
typeCreateGrid= (host:HTMLElementinterface HTMLElementinterfaceHTMLElementinterfaceHTMLElementThe HTMLElement interface represents any HTML element. MDN Reference, opts:GridOptionsinterface GridOptionsinterfaceGridOptionsinterfaceGridOptionsWorkbook, data, rendering, policy, and built-in UI options used to create a Grid.API reference →) =>Gridinterface GridinterfaceGridinterfaceGridImperative grid handle for document commands, events, rendering, and teardown.API reference →;
Field
Type
Default
Notes
workbook
Workbook
— (required)
Sheets, columns, row counts, and the activeSheet id.
presentation
"spreadsheet" | "data-grid"
"spreadsheet"
Positional A/B/C headers or semantic Column.header labels. Addressing and data rows are unchanged.
data
ColumnarData
undefined
Eager, in-memory, column-major values. Pass this ordatasource.
datasource
DataSource
undefined
Lazy, paged async source; rows fetched per visible window.
datasourceStorage
DataSourceStorageOptions
{ mode: "dense" }
Use { mode: "paged", chunkRows?, cacheBytes? } for allocation-lazy datasource storage.
renderer
"canvas" | "worker"
"canvas"
"worker" paints off-thread via OffscreenCanvas, falling back to canvas. See Worker rendering.
workerUrl
string | URL
undefined
Browser-fetchable module URL, e.g. "/sheetwrite/worker.js" after copying the package dist/; Vite can import @sheetwrite/core/worker?worker&url. See Worker rendering.
theme
Partial<Theme>
undefined
Overrides merged over DEFAULT_THEME and any --sheetwrite-* CSS vars. See Styling.
readOnly
boolean
false
When true, all mutating interactions (edit, clear, fill, paste, restyle) are disabled and the host gets aria-readonly="true".
protectionResolver
ProtectionResolver
undefined
Host callback for protected local mutations; no resolver means deny. Client-side UX policy only, never server authorization.
mutationPolicy
"atomic" | "partial"
"atomic"
Reject the whole local transaction on a denied protected operation, or apply allowed operations and report denied ones.
renderers
Record<string, CellRenderer>
{}
Custom cell renderers registered up front; reference one by name via Column.renderer. Also see defineCellRenderer.
editors
Record<string, CellEditor>
{}
Host-owned cell editors registered up front; reference one by name via Column.editor.
overscan
number
6
Row and visible-column positions painted on each viewport edge; 0 disables the buffer.
minColumns
number
workbook width
Minimum rendered/store column count, including empty spreadsheet padding columns.
config
GridConfig
undefined
Presence opts into the built-in toolbar (see below). Omit for no toolbar.
Framework adapters classify every GridOptions field centrally. workbook,
data, datasource, datasourceStorage, presentation, editors,
protectionResolver, mutationPolicy, and transactionResourceLimits create
an input-reset; renderer, workerUrl, and renderers create a
renderer-reset. theme, readOnly, config, overscan, and minColumns
update the existing grid live. Readiness includes the resulting generation and
reset reason.
Framework adapters also accept wasmSource. Initialization is process-wide and
first-source-wins: concurrent calls using the same source share one attempt, while
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. Changing 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.
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:
Semantic data-grid headers
constworkbookconst workbook: Workbookconstworkbook:Workbookconstworkbook:WorkbookLive workbook schema adopted by the store and updated by document operations.API reference →:Workbookinterface WorkbookinterfaceWorkbookinterfaceWorkbookLive workbook schema containing ordered sheets and the active sheet ID.API reference →= {
activeSheetWorkbook.activeSheet: stringinterfaceWorkbook {activeSheet:string;}interfaceWorkbook {activeSheet:string;}Active sheet ID and initial tab presented when the grid is created.API reference →: "people",
sheetsWorkbook.sheets: Sheet[]interfaceWorkbook {sheets:Sheet[];}interfaceWorkbook {sheets:Sheet[];}Sheets in display/tab order.API reference →: [{
idSheet.id: stringinterfaceSheet {id:string;}interfaceSheet {id:string;}Stable identifier, unique within the workbook and used by every cell address.API reference →: "people",
nameSheet.name: stringinterfaceSheet {name:string;}interfaceSheet {name:string;}User-facing sheet name shown in tabs and workbook exports.API reference →: "People",
rowCountSheet.rowCount: numberinterfaceSheet {rowCount:number;}interfaceSheet {rowCount:number;}Row count for both in-memory and datasource-backed sheets.API reference →: peopleconst people: readonly Record<string, CellScalar>[]constpeople:readonlyRecord<string, CellScalar>[]constpeople:readonlyRecord<string,CellScalar>[]API reference →.lengthReadonlyArray<Record<string, CellScalar>>.length: numberReadonlyArray<Record<string, CellScalar>>.length: numberReadonlyArray<Record<string, CellScalar>>.length: numberGets the length of the array. This is a number one higher than the highest element defined in an array.API reference →,
columnsSheet.columns: Column[]interfaceSheet {columns:Column[];}interfaceSheet {columns:Column[];}Ordered schema; array positions are the zero-based column coordinates.API reference →: [
{ keyColumn.key: stringinterfaceColumn {key:string;}interfaceColumn {key:string;}Non-empty key, unique within the sheet, used to map input and datasource values.API reference →: "name", headerColumn.header: stringinterfaceColumn {header:string;}interfaceColumn {header:string;}Schema label used by table exports and data-grid presentation headers.API reference →: "Customer name", widthColumn.width: numberinterfaceColumn {width:number;}interfaceColumn {width:number;}Unzoomed column width in CSS pixels.API reference →: 220, typeColumn.type: CellFormatinterfaceColumn {type:CellFormat;}interfaceColumn {type:CellFormat;}Controls cell input parsing and default value formatting for this column.API reference →: "text" },
{ keyColumn.key: stringinterfaceColumn {key:string;}interfaceColumn {key:string;}Non-empty key, unique within the sheet, used to map input and datasource values.API reference →: "status", headerColumn.header: stringinterfaceColumn {header:string;}interfaceColumn {header:string;}Schema label used by table exports and data-grid presentation headers.API reference →: "Account status", widthColumn.width: numberinterfaceColumn {width:number;}interfaceColumn {width:number;}Unzoomed column width in CSS pixels.API reference →: 160, typeColumn.type: CellFormatinterfaceColumn {type:CellFormat;}interfaceColumn {type:CellFormat;}Controls cell input parsing and default value formatting for this column.API reference →: "text" },
],
}],
};
constgridconst grid: Gridconstgrid:Gridconstgrid:GridThe imperative core grid this controller owns.API reference →=createGridfunction createGrid(host: HTMLElement, opts: GridOptions): GridfunctioncreateGrid(host:HTMLElement,opts:GridOptions,):GridfunctioncreateGrid(host:HTMLElement,opts:GridOptions,):GridCreates and mounts an imperative Grid in the supplied host element.API reference →(hostconst host: HTMLElementconsthost:HTMLElementconsthost:HTMLElement, {
workbookGridOptions.workbook: WorkbookinterfaceGridOptions {workbook:Workbook;}interfaceGridOptions {workbook:Workbook;}Live workbook schema adopted by the store and updated by document operations.API reference →,
dataGridOptions.data?: ColumnarData | undefinedinterfaceGridOptions {data?:ColumnarData|undefined;}interfaceGridOptions {data?:ColumnarData|undefined;}Eager column-major values loaded into workbook.activeSheet; use instead of datasource.API reference →,
presentationGridOptions.presentation?: GridPresentation | undefinedinterfaceGridOptions {presentation?:GridPresentation|undefined;}interfaceGridOptions {presentation?:GridPresentation|undefined;}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.API reference →: "data-grid",
});
The semantic header occupies the same header band as A/B/C; it does not
consume row 0. Cell addresses, formulas, selections, row numbers, clipboard
payloads, CSV/XLSX schema labels, mutation events, and datasource ranges keep
their existing zero-based data coordinates. Table exports use Column.header
in both presentation modes. The data-first Sheetwrite components select
"data-grid" automatically because every SimpleColumn requires a title.
Presentation is construction-bound. Changing it through a framework adapter
replaces the grid with reason: "input-reset" rather than renaming columns or
moving data in place.
Host-supplied editors
Set Column.editor to a key in GridOptions.editors. A custom editor takes
precedence over the built-in validation-list editor. If the key is absent,
Sheetwrite falls back to validation editing or its stock text/date editor.
Synchronous select editor
conststatusEditor:CellEditorinterface CellEditorinterfaceCellEditorinterfaceCellEditorFramework-neutral named editor definition registered through GridOptions.editors.API reference →= {
constselectconst select: HTMLSelectElementconstselect:HTMLSelectElementconstselect:HTMLSelectElement=documentvar document: Documentvar document:Documentvar document:Documentwindow.document returns a reference to the document contained in the window. MDN Reference.createElementDocument.createElement<"select">(tagName: "select", options?: ElementCreationOptions): HTMLSelectElement (+2 overloads)Document.createElement<"select">(tagName: "select", options?: ElementCreationOptions): HTMLSelectElement (+2 overloads)Document.createElement<"select">(tagName: "select", options?: ElementCreationOptions): HTMLSelectElement (+2 overloads)In an HTML document, the document.createElement() method creates the HTML element specified by localName, or an HTMLUnknownElement if localName isn't recognized. MDN Reference("select");
selectconst select: HTMLSelectElementconstselect:HTMLSelectElementconstselect:HTMLSelectElement.setAttributeElement.setAttribute(qualifiedName: string, value: string): voidElement.setAttribute(qualifiedName: string, value: string): voidElement.setAttribute(qualifiedName: string, value: string): voidThe setAttribute() method of the Element interface sets the value of an attribute on the specified element. MDN Reference("aria-label", contextcontext: CellEditorContextlet context:CellEditorContextlet context:CellEditorContextAPI reference →.labelCellEditorContext.label: stringinterfaceCellEditorContext {label:string;}interfaceCellEditorContext {label:string;}Menu row text. Defaults per action.API reference →);
for (constvalueconst value: stringconstvalue:stringconstvalue:stringof ["Prospect", "Active", "Paused"]) {
selectconst select: HTMLSelectElementconstselect:HTMLSelectElementconstselect:HTMLSelectElement.addHTMLSelectElement.add(element: HTMLOptionElement | HTMLOptGroupElement, before?: HTMLElement | number | null): voidHTMLSelectElement.add(element: HTMLOptionElement | HTMLOptGroupElement, before?: HTMLElement | number |null): voidHTMLSelectElement.add(element: HTMLOptionElement | HTMLOptGroupElement, before?: HTMLElement | number |null): voidThe HTMLSelectElement.add() method adds an element to the collection of option elements for this select element. MDN Reference(newOptionvar Option: new (text?: string, value?: string, defaultSelected?: boolean, selected?: boolean) => HTMLOptionElementvar Option:new (text?:string,value?:string,defaultSelected?:boolean,selected?:boolean,) =>HTMLOptionElementvar Option:new (text?:string,value?:string,defaultSelected?:boolean,selected?:boolean,) =>HTMLOptionElement(valueconst value: stringconstvalue:stringconstvalue:string, valueconst value: stringconstvalue:stringconstvalue:string));
}
selectconst select: HTMLSelectElementconstselect:HTMLSelectElementconstselect:HTMLSelectElement.valueHTMLSelectElement.value: stringinterfaceHTMLSelectElement {value:string;}interfaceHTMLSelectElement {value:string;}The HTMLSelectElement.value property contains the value of the first selected option element associated with this select element. MDN Reference=contextcontext: CellEditorContextlet context:CellEditorContextlet context:CellEditorContextAPI reference →.textCellEditorContext.text: stringinterfaceCellEditorContext {text:string;}interfaceCellEditorContext {text:string;}Formula source when the cell is a formula, else the literal display text.API reference →;
hosthost: HTMLElementlet host:HTMLElementlet host:HTMLElement.appendChildNode.appendChild<HTMLSelectElement>(node: HTMLSelectElement): HTMLSelectElementNode.appendChild<HTMLSelectElement>(node: HTMLSelectElement): HTMLSelectElementNode.appendChild<HTMLSelectElement>(node: HTMLSelectElement): HTMLSelectElementThe appendChild() method of the Node interface adds a node to the end of the list of children of a specified parent node. MDN Reference(selectconst select: HTMLSelectElementconstselect:HTMLSelectElementconstselect:HTMLSelectElement);
updateCellEditorInstance.update(context: CellEditorContext): voidCellEditorInstance.update(context: CellEditorContext): voidCellEditorInstance.update(context: CellEditorContext): voidUpdates a retained element after its value, style, theme, or geometry changes.API reference →(nextnext: CellEditorContextlet next:CellEditorContextlet next:CellEditorContextAPI reference →) {
selectconst select: HTMLSelectElementconstselect:HTMLSelectElementconstselect:HTMLSelectElement.setAttributeElement.setAttribute(qualifiedName: string, value: string): voidElement.setAttribute(qualifiedName: string, value: string): voidElement.setAttribute(qualifiedName: string, value: string): voidThe setAttribute() method of the Element interface sets the value of an attribute on the specified element. MDN Reference("aria-label", nextnext: CellEditorContextlet next:CellEditorContextlet next:CellEditorContextAPI reference →.labelCellEditorContext.label: stringinterfaceCellEditorContext {label:string;}interfaceCellEditorContext {label:string;}Menu row text. Defaults per action.API reference →);
selectconst select: HTMLSelectElementconstselect:HTMLSelectElementconstselect:HTMLSelectElement.valueHTMLSelectElement.value: stringinterfaceHTMLSelectElement {value:string;}interfaceHTMLSelectElement {value:string;}The HTMLSelectElement.value property contains the value of the first selected option element associated with this select element. MDN Reference=nextnext: CellEditorContextlet next:CellEditorContextlet next:CellEditorContextAPI reference →.textCellEditorContext.text: stringinterfaceCellEditorContext {text:string;}interfaceCellEditorContext {text:string;}Formula source when the cell is a formula, else the literal display text.API reference →;
returnselectconst select: HTMLSelectElementconstselect:HTMLSelectElementconstselect:HTMLSelectElement.valueHTMLSelectElement.value: stringinterfaceHTMLSelectElement {value:string;}interfaceHTMLSelectElement {value:string;}The HTMLSelectElement.value property contains the value of the first selected option element associated with this select element. MDN Reference;
destroyCellEditorInstance.destroy(): voidCellEditorInstance.destroy(): voidCellEditorInstance.destroy(): voidRuns immediately before a retained element is removed or replaced.API reference →() {
selectconst select: HTMLSelectElementconstselect:HTMLSelectElementconstselect:HTMLSelectElement.removeHTMLSelectElement.remove(): void (+1 overload)HTMLSelectElement.remove(): void (+1 overload)HTMLSelectElement.remove(): void (+1 overload)The HTMLSelectElement.remove() method removes the element at the specified index from the options collection for this select element. MDN Reference();
},
};
},
};
constgridconst grid: Gridconstgrid:Gridconstgrid:GridThe imperative core grid this controller owns.API reference →=createGridfunction createGrid(host: HTMLElement, opts: GridOptions): GridfunctioncreateGrid(host:HTMLElement,opts:GridOptions,):GridfunctioncreateGrid(host:HTMLElement,opts:GridOptions,):GridCreates and mounts an imperative Grid in the supplied host element.API reference →(hostconst host: HTMLElementconsthost:HTMLElementconsthost:HTMLElement, {
workbookGridOptions.workbook: WorkbookinterfaceGridOptions {workbook:Workbook;}interfaceGridOptions {workbook:Workbook;}Live workbook schema adopted by the store and updated by document operations.API reference →,
dataGridOptions.data?: ColumnarData | undefinedinterfaceGridOptions {data?:ColumnarData|undefined;}interfaceGridOptions {data?:ColumnarData|undefined;}Eager column-major values loaded into workbook.activeSheet; use instead of datasource.API reference →,
presentationGridOptions.presentation?: GridPresentation | undefinedinterfaceGridOptions {presentation?:GridPresentation|undefined;}interfaceGridOptions {presentation?:GridPresentation|undefined;}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.API reference →: "data-grid",
The returned value is parsed with the column's normal type and committed through
the same document transaction as stock editing. That preserves protection,
validation, mutation policy, undo/redo, change events, and edit-commit events.
An asynchronous commit remains bound to the data row captured at mount, even
when sorting or clearView() moves that row before the promise settles. If a
filter removes the row from the view, Sheetwrite cancels and aborts the pending
edit instead of retargeting another row. Returning a rejected promise,
undefined, or a non-string value from untyped JavaScript cancels without a
mutation. Enter commits and moves down, Tab/Shift+Tab commit and move
horizontally, and Escape cancels. Focus returns to the grid after commit or
cancel.
For remote choices, use the editor-owned AbortSignal; never let a late request
write into a destroyed editor:
Abortable async autocomplete
constassigneeAutocomplete:CellEditorinterface CellEditorinterfaceCellEditorinterfaceCellEditorFramework-neutral named editor definition registered through GridOptions.editors.API reference →= {
constinputconst input: HTMLInputElementconstinput:HTMLInputElementconstinput:HTMLInputElement=documentvar document: Documentvar document:Documentvar document:Documentwindow.document returns a reference to the document contained in the window. MDN Reference.createElementDocument.createElement<"input">(tagName: "input", options?: ElementCreationOptions): HTMLInputElement (+2 overloads)Document.createElement<"input">(tagName: "input", options?: ElementCreationOptions): HTMLInputElement (+2 overloads)Document.createElement<"input">(tagName: "input", options?: ElementCreationOptions): HTMLInputElement (+2 overloads)In an HTML document, the document.createElement() method creates the HTML element specified by localName, or an HTMLUnknownElement if localName isn't recognized. MDN Reference("input");
constlistconst list: HTMLDataListElementconstlist:HTMLDataListElementconstlist:HTMLDataListElement=documentvar document: Documentvar document:Documentvar document:Documentwindow.document returns a reference to the document contained in the window. MDN Reference.createElementDocument.createElement<"datalist">(tagName: "datalist", options?: ElementCreationOptions): HTMLDataListElement (+2 overloads)Document.createElement<"datalist">(tagName: "datalist", options?: ElementCreationOptions): HTMLDataListElement (+2 overloads)Document.createElement<"datalist">(tagName: "datalist", options?: ElementCreationOptions): HTMLDataListElement (+2 overloads)In an HTML document, the document.createElement() method creates the HTML element specified by localName, or an HTMLUnknownElement if localName isn't recognized. MDN Reference("datalist");
listconst list: HTMLDataListElementconstlist:HTMLDataListElementconstlist:HTMLDataListElement.idElement.id: stringinterfaceElement {id:string;}interfaceElement {id:string;}The id property of the Element interface represents the element's identifier, reflecting the id global attribute. MDN ReferenceAPI reference →=`assignees-${contextcontext: CellEditorContextlet context:CellEditorContextlet context:CellEditorContextAPI reference →.addressCellEditorContext.address: Readonly<CellAddress>interfaceCellEditorContext {address:Readonly<CellAddress>;}interfaceCellEditorContext {address:Readonly<CellAddress>;}Underlying data address, suitable for a set patch.API reference →.rowrow: numberlet row:numberlet row:number}-${contextcontext: CellEditorContextlet context:CellEditorContextlet context:CellEditorContextAPI reference →.addressCellEditorContext.address: Readonly<CellAddress>interfaceCellEditorContext {address:Readonly<CellAddress>;}interfaceCellEditorContext {address:Readonly<CellAddress>;}Underlying data address, suitable for a set patch.API reference →.colcol: numberlet col:numberlet col:number}`;
inputconst input: HTMLInputElementconstinput:HTMLInputElementconstinput:HTMLInputElement.setAttributeElement.setAttribute(qualifiedName: string, value: string): voidElement.setAttribute(qualifiedName: string, value: string): voidElement.setAttribute(qualifiedName: string, value: string): voidThe setAttribute() method of the Element interface sets the value of an attribute on the specified element. MDN Reference("list", listconst list: HTMLDataListElementconstlist:HTMLDataListElementconstlist:HTMLDataListElement.idElement.id: stringinterfaceElement {id:string;}interfaceElement {id:string;}The id property of the Element interface represents the element's identifier, reflecting the id global attribute. MDN ReferenceAPI reference →);
inputconst input: HTMLInputElementconstinput:HTMLInputElementconstinput:HTMLInputElement.setAttributeElement.setAttribute(qualifiedName: string, value: string): voidElement.setAttribute(qualifiedName: string, value: string): voidElement.setAttribute(qualifiedName: string, value: string): voidThe setAttribute() method of the Element interface sets the value of an attribute on the specified element. MDN Reference("role", "combobox");
inputconst input: HTMLInputElementconstinput:HTMLInputElementconstinput:HTMLInputElement.setAttributeElement.setAttribute(qualifiedName: string, value: string): voidElement.setAttribute(qualifiedName: string, value: string): voidElement.setAttribute(qualifiedName: string, value: string): voidThe setAttribute() method of the Element interface sets the value of an attribute on the specified element. MDN Reference("aria-label", contextcontext: CellEditorContextlet context:CellEditorContextlet context:CellEditorContextAPI reference →.labelCellEditorContext.label: stringinterfaceCellEditorContext {label:string;}interfaceCellEditorContext {label:string;}Menu row text. Defaults per action.API reference →);
inputconst input: HTMLInputElementconstinput:HTMLInputElementconstinput:HTMLInputElement.valueHTMLInputElement.value: stringinterfaceHTMLInputElement {value:string;}interfaceHTMLInputElement {value:string;}The value property of the HTMLInputElement interface represents the current value of the input element as a string. MDN Reference=contextcontext: CellEditorContextlet context:CellEditorContextlet context:CellEditorContextAPI reference →.initialInputCellEditorContext.initialInput: string | undefinedinterfaceCellEditorContext {initialInput:string|undefined;}interfaceCellEditorContext {initialInput:string|undefined;}API reference →??contextcontext: CellEditorContextlet context:CellEditorContextlet context:CellEditorContextAPI reference →.textCellEditorContext.text: stringinterfaceCellEditorContext {text:string;}interfaceCellEditorContext {text:string;}Formula source when the cell is a formula, else the literal display text.API reference →;
hosthost: HTMLElementlet host:HTMLElementlet host:HTMLElement.appendParentNode.append(...nodes: (Node | string)[]): voidParentNode.append(...nodes: (Node | string)[]): voidParentNode.append(...nodes: (Node | string)[]): voidInserts nodes after the last child of node, while replacing strings in nodes with equivalent Text nodes. Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated. MDN Reference(inputconst input: HTMLInputElementconstinput:HTMLInputElementconstinput:HTMLInputElement, listconst list: HTMLDataListElementconstlist:HTMLDataListElementconstlist:HTMLDataListElement);
voidfetchfunction fetch(input: string | URL | Request, init?: RequestInit): Promise<Response> (+2 overloads)
namespace fetchfunctionfetch(input:string|URL|Request, init?:RequestInit):Promise<Response> (+2overloads)namespacefetchfunctionfetch(input:string|URL|Request, init?:RequestInit):Promise<Response> (+2overloads)namespacefetchMDN Reference(`/api/people?q=${encodeURIComponentfunction encodeURIComponent(uriComponent: string | number | boolean): stringfunctionencodeURIComponent(uriComponent:string|number|boolean,):stringfunctionencodeURIComponent(uriComponent:string|number|boolean,):stringEncodes a text string as a valid component of a Uniform Resource Identifier (URI).@param uriComponent A value representing an unencoded URI component.(inputconst input: HTMLInputElementconstinput:HTMLInputElementconstinput:HTMLInputElement.valueHTMLInputElement.value: stringinterfaceHTMLInputElement {value:string;}interfaceHTMLInputElement {value:string;}The value property of the HTMLInputElement interface represents the current value of the input element as a string. MDN Reference)}`, {
signalRequestInit.signal?: AbortSignal | null | undefinedinterfaceRequestInit {signal?:AbortSignal|null|undefined;}interfaceRequestInit {signal?:|AbortSignal|null|undefined;}An AbortSignal to set request's signal.API reference →: contextcontext: CellEditorContextlet context:CellEditorContextlet context:CellEditorContextAPI reference →.signalCellEditorContext.signal: AbortSignalinterfaceCellEditorContext {signal:AbortSignal;}interfaceCellEditorContext {signal:AbortSignal;}Abort before or between bounded codec operations.API reference →,
})
.thenPromise<Response>.then<{
id: string;
name: string;
}[], never>(onfulfilled?: ((value: Response) => {
id: string;
name: string;
}[] | PromiseLike<{
id: string;
name: string;
}[]>) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<{
id: string;
name: string;
}[]>Promise<Response>.then<{id:string;name:string;}[], never>(onfulfilled?: ((value:Response) => {id: string;name: string;}[] |PromiseLike<{id:string;name:string;}[]>) |null|undefined, onrejected?: ((reason:any) => PromiseLike<never>) |null|undefined): Promise<{id:string;name:string;}[]>Promise<Response>.then<{id:string;name:string;}[], never>(onfulfilled?: ((value:Response) => {id: string;name: string;}[] |PromiseLike<{id:string;name:string;}[]>) |null|undefined, onrejected?: ((reason:any) => PromiseLike<never>) |null|undefined): Promise<{id:string;name:string;}[]>Attaches callbacks for the resolution and/or rejection of the Promise.@param onfulfilled The callback to execute when the Promise is resolved.@param onrejected The callback to execute when the Promise is rejected.@returns A Promise for the completion of which ever callback is executed.((responseresponse: Responselet response:Responselet response:Response) =>responseresponse: Responselet response:Responselet response:Response.jsonBody.json(): Promise<any>Body.json(): Promise<any>Body.json(): Promise<any>MDN Reference() asPromiseinterface Promise<T>interfacePromise<T>interfacePromise<T>Represents the completion of an asynchronous operation<Arrayinterface Array<T>interfaceArray<T>interfaceArray<T><{ idid: stringlet id:stringlet id:stringStable identity used by operations, history, and collaboration rebase.API reference →:string; namename: stringlet name:stringlet name:stringUser-facing sheet name shown in tabs and workbook exports.API reference →:string }>>)
.thenPromise<{ id: string; name: string; }[]>.then<void, never>(onfulfilled?: ((value: {
id: string;
name: string;
}[]) => void | PromiseLike<void>) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<void>Promise<{ id: string; name: string; }[]>.then<void, never>(onfulfilled?: ((value: {id:string;name:string;}[]) =>void| PromiseLike<void>) |null|undefined, onrejected?: ((reason:any) => PromiseLike<never>) |null|undefined): Promise<void>Promise<{ id: string; name: string; }[]>.then<void, never>(onfulfilled?: ((value: {id:string;name:string;}[]) =>void| PromiseLike<void>) |null|undefined, onrejected?: ((reason:any) => PromiseLike<never>) |null|undefined): Promise<void>Attaches callbacks for the resolution and/or rejection of the Promise.@param onfulfilled The callback to execute when the Promise is resolved.@param onrejected The callback to execute when the Promise is rejected.@returns A Promise for the completion of which ever callback is executed.((peoplepeople: {
id: string;
name: string;
}[]let people: {id:string;name:string;}[]let people: {id:string;name:string;}[]) => {
if (contextcontext: CellEditorContextlet context:CellEditorContextlet context:CellEditorContextAPI reference →.signalCellEditorContext.signal: AbortSignalinterfaceCellEditorContext {signal:AbortSignal;}interfaceCellEditorContext {signal:AbortSignal;}Abort before or between bounded codec operations.API reference →.abortedAbortSignal.aborted: booleaninterfaceAbortSignal {aborted:boolean;}interfaceAbortSignal {aborted:boolean;}The aborted read-only property returns a value that indicates whether the asynchronous operations the signal is communicating with are aborted (true) or not (false). MDN Reference) return;
listconst list: HTMLDataListElementconstlist:HTMLDataListElementconstlist:HTMLDataListElement.replaceChildrenParentNode.replaceChildren(...nodes: (Node | string)[]): voidParentNode.replaceChildren(...nodes: (Node | string)[]): voidParentNode.replaceChildren(...nodes: (Node | string)[]): voidReplace all children of node with nodes, while replacing strings in nodes with equivalent Text nodes. Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated. MDN Reference(
...peoplepeople: {
id: string;
name: string;
}[]let people: {id:string;name:string;}[]let people: {id:string;name:string;}[].mapArray<{ id: string; name: string; }>.map<HTMLOptionElement>(callbackfn: (value: {
id: string;
name: string;
}, index: number, array: {
id: string;
name: string;
}[]) => HTMLOptionElement, thisArg?: any): HTMLOptionElement[]Array<{ id: string; name: string; }>.map<HTMLOptionElement>(callbackfn: (value: {id:string;name:string;}, index:number, array: {id:string;name:string;}[]) => HTMLOptionElement, thisArg?: any): HTMLOptionElement[]Array<{ id: string; name: string; }>.map<HTMLOptionElement>(callbackfn: (value: {id:string;name:string;}, index:number, array: {id:string;name:string;}[]) => HTMLOptionElement, thisArg?: any): HTMLOptionElement[]Calls a defined callback function on each element of an array, and returns an array that contains the results.@param callbackfn A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.@param thisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.((personperson: {
id: string;
name: string;
}let person: {id:string;name:string;}let person: {id:string;name:string;}) => {
constoptionconst option: HTMLOptionElementconstoption:HTMLOptionElementconstoption:HTMLOptionElement=documentvar document: Documentvar document:Documentvar document:Documentwindow.document returns a reference to the document contained in the window. MDN Reference.createElementDocument.createElement<"option">(tagName: "option", options?: ElementCreationOptions): HTMLOptionElement (+2 overloads)Document.createElement<"option">(tagName: "option", options?: ElementCreationOptions): HTMLOptionElement (+2 overloads)Document.createElement<"option">(tagName: "option", options?: ElementCreationOptions): HTMLOptionElement (+2 overloads)In an HTML document, the document.createElement() method creates the HTML element specified by localName, or an HTMLUnknownElement if localName isn't recognized. MDN Reference("option");
optionconst option: HTMLOptionElementconstoption:HTMLOptionElementconstoption:HTMLOptionElement.valueHTMLOptionElement.value: stringinterfaceHTMLOptionElement {value:string;}interfaceHTMLOptionElement {value:string;}The value property of the HTMLOptionElement interface represents the value of the option element as a string, or the empty string if no value is set. MDN Reference=personperson: {
id: string;
name: string;
}let person: {id:string;name:string;}let person: {id:string;name:string;}.namename: stringlet name:stringlet name:stringUser-facing sheet name shown in tabs and workbook exports.API reference →;
optionconst option: HTMLOptionElementconstoption:HTMLOptionElementconstoption:HTMLOptionElement.datasetHTMLOrSVGElement.dataset: DOMStringMapinterfaceHTMLOrSVGElement {dataset:DOMStringMap;}interfaceHTMLOrSVGElement {dataset:DOMStringMap;}MDN Reference.idDOMStringMap[string]: string | undefinedDOMStringMap[string]: string |undefinedDOMStringMap[string]: string |undefinedStable identity used by operations, history, and collaboration rebase.API reference →=personperson: {
id: string;
name: string;
}let person: {id:string;name:string;}let person: {id:string;name:string;}.idid: stringlet id:stringlet id:stringStable identity used by operations, history, and collaboration rebase.API reference →;
.catchPromise<void>.catch<void>(onrejected?: ((reason: any) => void | PromiseLike<void>) | null | undefined): Promise<void>Promise<void>.catch<void>(onrejected?: ((reason:any) =>void| PromiseLike<void>) |null|undefined): Promise<void>Promise<void>.catch<void>(onrejected?: ((reason:any) =>void| PromiseLike<void>) |null|undefined): Promise<void>Attaches a callback for only the rejection of the Promise.@param onrejected The callback to execute when the Promise is rejected.@returns A Promise for the completion of the callback.((error:unknown) => {
if (!(errorerror: unknownlet error:unknownlet error:unknowninstanceofDOMExceptionvar DOMException: {
new (message?: string, name?: string): DOMException;
prototype: DOMException;
readonly INDEX_SIZE_ERR: 1;
readonly DOMSTRING_SIZE_ERR: 2;
readonly HIERARCHY_REQUEST_ERR: 3;
readonly WRONG_DOCUMENT_ERR: 4;
readonly INVALID_CHARACTER_ERR: 5;
readonly NO_DATA_ALLOWED_ERR: 6;
readonly NO_MODIFICATION_ALLOWED_ERR: 7;
readonly NOT_FOUND_ERR: 8;
readonly NOT_SUPPORTED_ERR: 9;
readonly INUSE_ATTRIBUTE_ERR: 10;
readonly INVALID_STATE_ERR: 11;
readonly SYNTAX_ERR: 12;
readonly INVALID_MODIFICATION_ERR: 13;
readonly NAMESPACE_ERR: 14;
readonly INVALID_ACCESS_ERR: 15;
... 9 more ...;
readonly DATA_CLONE_ERR: 25;
}var DOMException: {new (message?:string, name?:string):DOMException;prototype:DOMException;readonlyINDEX_SIZE_ERR:1;readonlyDOMSTRING_SIZE_ERR:2;readonlyHIERARCHY_REQUEST_ERR:3;readonlyWRONG_DOCUMENT_ERR:4;readonlyINVALID_CHARACTER_ERR:5;readonlyNO_DATA_ALLOWED_ERR:6;readonlyNO_MODIFICATION_ALLOWED_ERR:7;readonlyNOT_FOUND_ERR:8;readonlyNOT_SUPPORTED_ERR:9;readonlyINUSE_ATTRIBUTE_ERR:10;readonlyINVALID_STATE_ERR:11;readonlySYNTAX_ERR:12;readonlyINVALID_MODIFICATION_ERR:13;readonlyNAMESPACE_ERR:14;readonlyINVALID_ACCESS_ERR:15;...9more ...;readonlyDATA_CLONE_ERR:25;}var DOMException: {new (message?:string, name?:string):DOMException;prototype:DOMException;readonlyINDEX_SIZE_ERR:1;readonlyDOMSTRING_SIZE_ERR:2;readonlyHIERARCHY_REQUEST_ERR:3;readonlyWRONG_DOCUMENT_ERR:4;readonlyINVALID_CHARACTER_ERR:5;readonlyNO_DATA_ALLOWED_ERR:6;readonlyNO_MODIFICATION_ALLOWED_ERR:7;readonlyNOT_FOUND_ERR:8;readonlyNOT_SUPPORTED_ERR:9;readonlyINUSE_ATTRIBUTE_ERR:10;readonlyINVALID_STATE_ERR:11;readonlySYNTAX_ERR:12;readonlyINVALID_MODIFICATION_ERR:13;readonlyNAMESPACE_ERR:14;readonlyINVALID_ACCESS_ERR:15;...9more ...;readonlyDATA_CLONE_ERR:25;}The DOMException interface represents an abnormal event (called an exception) that occurs as a result of calling a method or accessing a property of a web API. MDN Reference An abnormal event (called an exception) which occurs as a result of calling a method or accessing a property of a web API&&errorerror: DOMExceptionlet error:DOMExceptionlet error:DOMException.nameDOMException.name: stringinterfaceDOMException {name:string;}interfaceDOMException {name:string;}The name read-only property of the one of the strings associated with an error name. MDN ReferenceAPI reference →==="AbortError")) throwerrorerror: unknownlet error:unknownlet error:unknown;
});
return {
updateCellEditorInstance.update(context: CellEditorContext): voidCellEditorInstance.update(context: CellEditorContext): voidCellEditorInstance.update(context: CellEditorContext): voidUpdates a retained element after its value, style, theme, or geometry changes.API reference →(nextnext: CellEditorContextlet next:CellEditorContextlet next:CellEditorContextAPI reference →) {
inputconst input: HTMLInputElementconstinput:HTMLInputElementconstinput:HTMLInputElement.setAttributeElement.setAttribute(qualifiedName: string, value: string): voidElement.setAttribute(qualifiedName: string, value: string): voidElement.setAttribute(qualifiedName: string, value: string): voidThe setAttribute() method of the Element interface sets the value of an attribute on the specified element. MDN Reference("aria-label", nextnext: CellEditorContextlet next:CellEditorContextlet next:CellEditorContextAPI reference →.labelCellEditorContext.label: stringinterfaceCellEditorContext {label:string;}interfaceCellEditorContext {label:string;}Menu row text. Defaults per action.API reference →);
awaitPromisevar Promise: PromiseConstructorvar Promise:PromiseConstructorvar Promise:PromiseConstructorRepresents the completion of an asynchronous operation.resolvePromiseConstructor.resolve(): Promise<void> (+2 overloads)PromiseConstructor.resolve(): Promise<void> (+2 overloads)PromiseConstructor.resolve(): Promise<void> (+2 overloads)Creates a new resolved promise.@returns A resolved promise.();
returninputconst input: HTMLInputElementconstinput:HTMLInputElementconstinput:HTMLInputElement.valueHTMLInputElement.value: stringinterfaceHTMLInputElement {value:string;}interfaceHTMLInputElement {value:string;}The value property of the HTMLInputElement interface represents the current value of the input element as a string. MDN Reference;
destroyCellEditorInstance.destroy(): voidCellEditorInstance.destroy(): voidCellEditorInstance.destroy(): voidRuns immediately before a retained element is removed or replaced.API reference →() {
One retained wrapper and one CellEditorInstance exist per active edit:
Hook / value
Guarantee
mount(host, context)
Runs once. The host is positioned over the active cell.
context.address / viewAddress
Canonical data-row and current displayed-row snapshots. They are readonly and mutating a JavaScript object received by the editor cannot retarget the edit.
context.value / text / initialInput
Resolved scalar, formatted text, and optional typed character.
context.label
Accessible name derived from semantic/positional header plus row number.
context.signal
Aborted before the editor's cancel() or destroy() hook on cancel, commit, reset, or unmount.
context.commit() / cancel()
Optional editor-driven completion using the canonical path. A non-string commit from untyped JavaScript cancels safely.
update(context)
External value, theme, zoom, view permutation, or geometry-sensitive state changed without replacing ownership.
reposition(rect)
The active cell moved or resized.
commit()
May return input synchronously or asynchronously; duplicate completion is ignored.
cancel()
Notification before a host-requested cancellation; the signal is already aborted.
destroy()
Runs exactly once; late async work must observe the aborted signal. A thrown hook error is reported without interrupting Sheetwrite's DOM, listener, or store cleanup.
editors is construction-bound so React/Vue/Svelte resets safely abort and
destroy an active editor before publishing the new grid generation. All adapters
accept the same registry:
workbookGridOptions.workbook: WorkbookinterfaceGridOptions {workbook:Workbook;}interfaceGridOptions {workbook:Workbook;}Live workbook schema adopted by the store and updated by document operations.API reference →={workbookconst workbook: Workbookconstworkbook:Workbookconstworkbook:WorkbookLive workbook schema adopted by the store and updated by document operations.API reference →}
dataGridOptions.data?: ColumnarData | undefinedinterfaceGridOptions {data?:ColumnarData|undefined;}interfaceGridOptions {data?:ColumnarData|undefined;}Eager column-major values loaded into workbook.activeSheet; use instead of datasource.API reference →={dataconst data: ColumnarDataconstdata:ColumnarDataconstdata:ColumnarDataEager column-major values loaded into workbook.activeSheet; use instead of datasource.API reference →}
presentationGridOptions.presentation?: GridPresentation | undefinedinterfaceGridOptions {presentation?:GridPresentation|undefined;}interfaceGridOptions {presentation?:GridPresentation|undefined;}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.API reference →="data-grid"
@command-state-change="({ states }) => commandStates = states"
/>
Svelte
<SheetwriteGridconst SheetwriteGrid: Component<SheetwriteGridProps<RowBridgeId>, {}, "grid">constSheetwriteGrid:Component<SheetwriteGridProps<RowBridgeId>,{},"grid">constSheetwriteGrid:Component<SheetwriteGridProps<RowBridgeId>,{},"grid">Advanced framework component for workbook data or datasource input.API reference →
{workbookworkbook: Workbooklet workbook:Workbooklet workbook:WorkbookLive workbook schema adopted by the store and updated by document operations.API reference →}
{datadata: ColumnarDatalet data:ColumnarDatalet data:ColumnarDataEager column-major values loaded into workbook.activeSheet; use instead of datasource.API reference →}
The cancellable request API owns one visible-window generation. Pages can carry
authoritative formula source and style rather than only resolved scalars:
`/sheets/${encodeURIComponentfunction encodeURIComponent(uriComponent: string | number | boolean): stringfunctionencodeURIComponent(uriComponent:string|number|boolean,):stringfunctionencodeURIComponent(uriComponent:string|number|boolean,):stringEncodes a text string as a valid component of a Uniform Resource Identifier (URI).@param uriComponent A value representing an unencoded URI component.(sheetsheet: stringlet sheet:stringlet sheet:stringSheet identity used by the simple data-first adapter. Defaults to sheet1.API reference →)}?start=${startstart: numberlet start:numberlet start:numberInclusive row index.API reference →}&end=${endend: numberlet end:numberlet end:numberExclusive row index.API reference →}`,
{ signalRequestInit.signal?: AbortSignal | null | undefinedinterfaceRequestInit {signal?:AbortSignal|null|undefined;}interfaceRequestInit {signal?:|AbortSignal|null|undefined;}An AbortSignal to set request's signal.API reference → },
);
if (!responseconst response: Responseconstresponse:Responseconstresponse:Response.okResponse.ok: booleaninterfaceResponse {ok:boolean;}interfaceResponse {ok:boolean;}The ok read-only property of the Response interface contains a Boolean stating whether the response was successful (status in the range 200-299) or not. MDN Reference) thrownewErrorvar Error: ErrorConstructor
new (message?: string, options?: ErrorOptions) => Error (+2 overloads)var Error:ErrorConstructornew (message?:string, options?:ErrorOptions) =>Error (+2 overloads)var Error:ErrorConstructornew (message?:string, options?:ErrorOptions) =>Error (+2 overloads)(`Datasource request failed: ${responseconst response: Responseconstresponse:Responseconstresponse:Response.statusResponse.status: numberinterfaceResponse {status:number;}interfaceResponse {status:number;}The status read-only property of the Response interface contains the HTTP status codes of the response. MDN Reference}`);
startDataSourcePage.start: numberinterfaceDataSourcePage {start:number;}interfaceDataSourcePage {start:number;}Inclusive row index of the first returned row.API reference →,
revisionDataSourcePage.revision?: string | number | undefinedinterfaceDataSourcePage {revision?:string|number|undefined;}interfaceDataSourcePage {revision?:string|number|undefined;}API reference →: responseconst response: Responseconstresponse:Responseconstresponse:Response.headersResponse.headers: HeadersinterfaceResponse {headers:Headers;}interfaceResponse {headers:Headers;}The headers read-only property of the with the response. MDN Reference.getHeaders.get(name: string): string | nullHeaders.get(name: string): string |nullHeaders.get(name: string): string |nullThe get() method of the Headers interface returns a byte string of all the values of a header within a Headers object with a given name. MDN Reference("etag") ??revisionrevision: numberlet revision:numberlet revision:number,
rowsDataSourcePage.rows: RowData[]interfaceDataSourcePage {rows:RowData[];}interfaceDataSourcePage {rows:RowData[];}end-exclusive row rangeAPI reference →: recordsconst records: ApiRow[]constrecords:ApiRow[]constrecords:ApiRow[].mapArray<ApiRow>.map<{
label: string;
quantity: number;
price: number;
total: {
value: {
kind: "formula";
src: string;
};
style: {
numberFormat: string;
bold: true;
};
};
}>(callbackfn: (value: ApiRow, index: number, array: ApiRow[]) => {
label: string;
quantity: number;
price: number;
total: {
value: {
kind: "formula";
src: string;
};
style: {
numberFormat: string;
bold: true;
};
};
}, thisArg?: any): {
label: string;
quantity: number;
price: number;
total: {
value: {
kind: "formula";
src: string;
};
style: {
numberFormat: string;
bold: true;
};
};
}[]Array<ApiRow>.map<{label:string;quantity:number;price:number;total: {value: {kind:"formula";src:string;};style: {numberFormat:string;bold:true;};};}>(callbackfn: (value:ApiRow, index:number, array:ApiRow[]) => {label:string;quantity:number;price:number;total: {value: {kind:"formula";src:string;};style: {numberFormat:string;bold:true;};};}, thisArg?:any): {label:string;quantity:number;price:number;total: {value: {kind:"formula";src:string;};style: {numberFormat:string;bold:true;};};}[]Array<ApiRow>.map<{label:string;quantity:number;price:number;total: {value: {kind:"formula";src:string;};style: {numberFormat:string;bold:true;};};}>(callbackfn: (value:ApiRow, index:number, array:ApiRow[]) => {label:string;quantity:number;price:number;total: {value: {kind:"formula";src:string;};style: {numberFormat:string;bold:true;};};}, thisArg?:any): {label:string;quantity:number;price:number;total: {value: {kind:"formula";src:string;};style: {numberFormat:string;bold:true;};};}[]Calls a defined callback function on each element of an array, and returns an array that contains the results.@param callbackfn A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.@param thisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.((recordrecord: ApiRowlet record:ApiRowlet record:ApiRow, indexindex: numberlet index:numberlet index:number) => ({
stylestyle: {
numberFormat: string;
bold: true;
}let style: {numberFormat:string;bold:true;}let style: {numberFormat:string;bold:true;}Optional override merged over the deterministic blue/underline link style.API reference →: { numberFormatnumberFormat: stringlet numberFormat:stringlet numberFormat:stringExcel number-format code, e.g. "#,##0.00"API reference →: "$#,##0.00", boldbold: truelet bold:truelet bold:trueUses the bold variant of the theme font.API reference →: true },
},
})),
};
},
};
rows may contain scalars, CellValue objects, or
{ value: CellValue, style?: CellStyle } wrappers. Hydrated formulas,
references, and styles do not emit user change events. Short pages mark only the
returned rows loaded; malformed ranges emit datasource-error and remain
retryable. Resetting or destroying the grid aborts outstanding requests, and a
late page never overwrites a cell edited after that request began.
Dense storage is the default. { mode: "paged" } allocates
power-of-two row chunks only for loaded or locally edited areas; cacheBytes
bounds clean cached chunks, while dirty chunks remain pinned until
acknowledgement. Full-sheet queries and exports report incomplete data until all
required pages are loaded. Store.queryCapability(sheet) and
getCellLoadState(addr) expose that state.
Default chunk/cache values and eviction behavior are listed in Compatibility and limits.
Serializable documents
Use WorkbookSnapshot plus validateWorkbookSnapshot() at persistence
boundaries. schemaVersion: 1 rejects unsupported future schemas with
structured errors. DocumentOp is the exhaustive reducer operation union,
including metadata and sheet lifecycle operations.
Session-only grid options such as renderer, readOnly, local zoom, selection,
scroll, search, and temporary highlights never belong in a snapshot.
createGridFromSnapshot(host, snapshot, options) validates and hydrates every
sheet before mounting. Hydration emits no change event or undo entry.
grid.exportSnapshot() uses bulk sheet reads and returns deterministic sparse
blocks. grid.applyRemoteOperations(operations) emits a change with
source: "remote" while remaining outside local undo history and
SyncCoordinator's outgoing queue. SyncCoordinator queues each non-empty local
transaction as an immutable mutation record. Its serverVersion option is
required and should come from the loaded snapshot.
sendNext() and retry(id) are host-controlled; retries retain the original
ID. subscribe(source) accepts a transport-neutral callback source and validates
strict version order. Use MemoryPersistenceAdapter as an executable,
server-sequenced reference—not as durable storage. Adapter methods accept
AbortSignal; transport failures use PersistenceError, while version
conflicts are typed commit responses that retain local work.
A CellRenderer paints or retains a DOM node for each cell in the rendered
window. When dom is present, it owns the cell content (the canvas still paints
the cell background, border, headers, and grid lines):
Partial example
interfaceCellRendererinterface CellRenderer
interface CellRendererinterfaceCellRendererinterfaceCellRendererinterfaceCellRendererinterfaceCellRendererCustom cell renderer hooks for the main-thread canvas or retained DOM overlay.API reference → {
canvasCellRenderer.canvas?(ctx: CanvasRenderingContext2D, c: CellPaintContext): voidCellRenderer.canvas?(ctx:CanvasRenderingContext2D, c:CellPaintContext):voidCellRenderer.canvas?(ctx:CanvasRenderingContext2D, c:CellPaintContext):void?(ctx:CanvasRenderingContext2Dinterface CanvasRenderingContext2DinterfaceCanvasRenderingContext2DinterfaceCanvasRenderingContext2DThe CanvasRenderingContext2D interface, part of the Canvas API, provides the 2D rendering context for the drawing surface of a canvas element. MDN Reference, c:CellPaintContextinterface CellPaintContextinterfaceCellPaintContextinterfaceCellPaintContextRead-only cell value and screen geometry supplied to a custom renderer.API reference →):void;
domCellRenderer.dom?(c: CellPaintContext): HTMLElementCellRenderer.dom?(c:CellPaintContext):HTMLElementCellRenderer.dom?(c:CellPaintContext):HTMLElementCreates a fresh, detached element uniquely owned by one retained DOM cell.API reference →?(c:CellPaintContextinterface CellPaintContextinterfaceCellPaintContextinterfaceCellPaintContextRead-only cell value and screen geometry supplied to a custom renderer.API reference →):HTMLElementinterface HTMLElementinterfaceHTMLElementinterfaceHTMLElementThe HTMLElement interface represents any HTML element. MDN Reference;
updateCellRenderer.update?(element: HTMLElement, c: CellPaintContext): voidCellRenderer.update?(element:HTMLElement, c:CellPaintContext):voidCellRenderer.update?(element:HTMLElement, c:CellPaintContext):voidUpdates a retained element after its value, style, theme, or geometry changes.API reference →?(elementelement: HTMLElementlet element:HTMLElementlet element:HTMLElementThe shell's root element (already appended to the mount host).API reference →:HTMLElementinterface HTMLElementinterfaceHTMLElementinterfaceHTMLElementThe HTMLElement interface represents any HTML element. MDN Reference, c:CellPaintContextinterface CellPaintContextinterfaceCellPaintContextinterfaceCellPaintContextRead-only cell value and screen geometry supplied to a custom renderer.API reference →):void;
destroyCellRenderer.destroy?(element: HTMLElement): voidCellRenderer.destroy?(element:HTMLElement):voidCellRenderer.destroy?(element:HTMLElement):voidRuns immediately before a retained element is removed or replaced.API reference →?(elementelement: HTMLElementlet element:HTMLElementlet element:HTMLElementThe shell's root element (already appended to the mount host).API reference →:HTMLElementinterface HTMLElementinterfaceHTMLElementinterfaceHTMLElementThe HTMLElement interface represents any HTML element. MDN Reference):void;
}
dom creates an element when a cell enters the bounded rendered window.
update receives that same element after values, styles, theme, zoom, size, or
scroll geometry change. destroy runs immediately before the element leaves
the window, is replaced by a newly registered renderer, or its grid is reset or
destroyed. Implement update to preserve focus and element-local state. 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, return a native control (or add a non-negative tabindex), give it
an accessible name, and 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.
GridConfig (toolbar)
Set config to show the built-in toolbar. Each flag toggles one control; all
flags default to true when config is present. The one special case is
toolbar: false, which suppresses the toolbar entirely.
Partial example
createGridfunction createGrid(host: HTMLElement, opts: GridOptions): GridfunctioncreateGrid(host:HTMLElement,opts:GridOptions,):GridfunctioncreateGrid(host:HTMLElement,opts:GridOptions,):GridCreates and mounts an imperative Grid in the supplied host element.API reference →(hostconst host: HTMLElementconsthost:HTMLElementconsthost:HTMLElement, { workbookGridOptions.workbook: WorkbookinterfaceGridOptions {workbook:Workbook;}interfaceGridOptions {workbook:Workbook;}Live workbook schema adopted by the store and updated by document operations.API reference →, configGridOptions.config?: GridConfig | undefinedinterfaceGridOptions {config?:GridConfig|undefined;}interfaceGridOptions {config?:GridConfig|undefined;}Built-in UI controls; providing an object enables the toolbar unless toolbar is false.API reference →: {} }); // toolbar with every control
createGridfunction createGrid(host: HTMLElement, opts: GridOptions): GridfunctioncreateGrid(host:HTMLElement,opts:GridOptions,):GridfunctioncreateGrid(host:HTMLElement,opts:GridOptions,):GridCreates and mounts an imperative Grid in the supplied host element.API reference →(hostconst host: HTMLElementconsthost:HTMLElementconsthost:HTMLElement, { workbookGridOptions.workbook: WorkbookinterfaceGridOptions {workbook:Workbook;}interfaceGridOptions {workbook:Workbook;}Live workbook schema adopted by the store and updated by document operations.API reference →, configGridOptions.config?: GridConfig | undefinedinterfaceGridOptions {config?:GridConfig|undefined;}interfaceGridOptions {config?:GridConfig|undefined;}Built-in UI controls; providing an object enables the toolbar unless toolbar is false.API reference →: { sortGridConfig.sort?: boolean | undefinedinterfaceGridConfig {sort?:boolean|undefined;}interfaceGridConfig {sort?:boolean|undefined;}Show ascending and descending sort controls in the default toolbar (default true).API reference →: false } }); // toolbar, no sort control
createGridfunction createGrid(host: HTMLElement, opts: GridOptions): GridfunctioncreateGrid(host:HTMLElement,opts:GridOptions,):GridfunctioncreateGrid(host:HTMLElement,opts:GridOptions,):GridCreates and mounts an imperative Grid in the supplied host element.API reference →(hostconst host: HTMLElementconsthost:HTMLElementconsthost:HTMLElement, { workbookGridOptions.workbook: WorkbookinterfaceGridOptions {workbook:Workbook;}interfaceGridOptions {workbook:Workbook;}Live workbook schema adopted by the store and updated by document operations.API reference →, configGridOptions.config?: GridConfig | undefinedinterfaceGridOptions {config?:GridConfig|undefined;}interfaceGridOptions {config?:GridConfig|undefined;}Built-in UI controls; providing an object enables the toolbar unless toolbar is false.API reference →: { toolbarGridConfig.toolbar?: boolean | ToolbarItem[] | undefinedinterfaceGridConfig {toolbar?:boolean|ToolbarItem[] |undefined;}interfaceGridConfig {toolbar?:|boolean|ToolbarItem[]|undefined;}Show the built-in toolbar (true), hide it (false), or supply a custom item list.API reference →: false } }); // no toolbar
createGridfunction createGrid(host: HTMLElement, opts: GridOptions): GridfunctioncreateGrid(host:HTMLElement,opts:GridOptions,):GridfunctioncreateGrid(host:HTMLElement,opts:GridOptions,):GridCreates and mounts an imperative Grid in the supplied host element.API reference →(hostconst host: HTMLElementconsthost:HTMLElementconsthost:HTMLElement, { workbookGridOptions.workbook: WorkbookinterfaceGridOptions {workbook:Workbook;}interfaceGridOptions {workbook:Workbook;}Live workbook schema adopted by the store and updated by document operations.API reference → }); // no toolbar (config omitted)
Flag
Type
Default
Control
toolbar
boolean
true¹
Master switch. false removes the toolbar.
bold
boolean
true
Bold toggle.
italic
boolean
true
Italic toggle.
align
boolean
true
Left / center / right alignment.
textColor
boolean
true
Text color picker.
fillColor
boolean
true
Fill (background) color picker.
border
boolean
true
Border control.
clearFormat
boolean
true
Clear formatting.
merge
boolean
true
Merge / unmerge selection.
sort
boolean
true
Sort the selected column.
export
boolean
true
CSV / XLSX export buttons.
undo
boolean
true
Undo / redo buttons (also bound to Ctrl+Z / Ctrl+Shift+Z).
¹ "Default true" means: when you supply a config object at all. With no
config there is no toolbar.
The export flag always enables CSV. Its XLSX button requires an explicit
optional installation and import "@sheetwrite/xlsx/register" before use; the
framework packages do not install an XLSX backend.
Direct grid.exportXlsx(...) calls reject on failure; built-in toolbar and
context-menu actions report the same failure through one export-error event.
Every control acts on the current selection — see Interaction.
Host-owned command state
Host chrome can use grid.actions without duplicating selection/history logic.
Query one command with grid.getCommandState(name) or subscribe to the complete
snapshot through command-state-change (onCommandStateChange in React/Svelte,
@command-state-change in Vue):
Accessible host toolbar
constupdateconst update: (bold: GridCommandState, undo: GridCommandState) => voidconstupdate: (bold:GridCommandState,undo:GridCommandState,) =>voidconstupdate: (bold:GridCommandState,undo:GridCommandState,) =>voidUpdates a retained element after its value, style, theme, or geometry changes.API reference →= (boldbold: GridCommandStatelet bold:GridCommandStatelet bold:GridCommandStateUses the bold variant of the theme font.API reference →:GridCommandStateinterface GridCommandStateinterfaceGridCommandStateinterfaceGridCommandStateObservable availability and selection-derived activity for one command.API reference →, undoundo: GridCommandStatelet undo:GridCommandStatelet undo:GridCommandStateUndo the last recorded cell edit.API reference →:GridCommandStateinterface GridCommandStateinterfaceGridCommandStateinterfaceGridCommandStateObservable availability and selection-derived activity for one command.API reference →) => {
undoButtonconst undoButton: HTMLButtonElementconstundoButton:HTMLButtonElementconstundoButton:HTMLButtonElement.disabledHTMLButtonElement.disabled: booleaninterfaceHTMLButtonElement {disabled:boolean;}interfaceHTMLButtonElement {disabled:boolean;}The HTMLButtonElement.disabled property indicates whether the control is disabled, meaning that it does not accept any clicks. MDN ReferenceAPI reference →=undoundo: GridCommandStatelet undo:GridCommandStatelet undo:GridCommandStateUndo the last recorded cell edit.API reference →.disabledGridCommandState.disabled: booleaninterfaceGridCommandState {disabled:boolean;}interfaceGridCommandState {disabled:boolean;}Static or context-aware disabled state.API reference →;
boldButtonconst boldButton: HTMLButtonElementconstboldButton:HTMLButtonElementconstboldButton:HTMLButtonElement.disabledHTMLButtonElement.disabled: booleaninterfaceHTMLButtonElement {disabled:boolean;}interfaceHTMLButtonElement {disabled:boolean;}The HTMLButtonElement.disabled property indicates whether the control is disabled, meaning that it does not accept any clicks. MDN ReferenceAPI reference →=boldbold: GridCommandStatelet bold:GridCommandStatelet bold:GridCommandStateUses the bold variant of the theme font.API reference →.disabledGridCommandState.disabled: booleaninterfaceGridCommandState {disabled:boolean;}interfaceGridCommandState {disabled:boolean;}Static or context-aware disabled state.API reference →;
boldButtonconst boldButton: HTMLButtonElementconstboldButton:HTMLButtonElementconstboldButton:HTMLButtonElement.setAttributeElement.setAttribute(qualifiedName: string, value: string): voidElement.setAttribute(qualifiedName: string, value: string): voidElement.setAttribute(qualifiedName: string, value: string): voidThe setAttribute() method of the Element interface sets the value of an attribute on the specified element. MDN Reference(
"aria-pressed",
boldbold: GridCommandStatelet bold:GridCommandStatelet bold:GridCommandStateUses the bold variant of the theme font.API reference →.activityGridCommandState.activity: "inactive" | "active" | "mixed"interfaceGridCommandState {activity:"inactive"|"active"|"mixed";}interfaceGridCommandState {activity:|"inactive"|"active"|"mixed";}API reference →==="mixed"?"mixed":Stringvar String: StringConstructor
(value?: any) => stringvar String:StringConstructor;(value?:any) => stringvar String:StringConstructor;(value?:any) => stringAllows manipulation and formatting of text strings and determination and location of substrings within strings.(boldbold: GridCommandStatelet bold:GridCommandStatelet bold:GridCommandStateUses the bold variant of the theme font.API reference →.activityGridCommandState.activity: "inactive" | "active"interfaceGridCommandState {activity:"inactive"|"active";}interfaceGridCommandState {activity:"inactive"|"active";}API reference →==="active"),
);
};
updateconst update: (bold: GridCommandState, undo: GridCommandState) => voidconstupdate: (bold:GridCommandState,undo:GridCommandState,) =>voidconstupdate: (bold:GridCommandState,undo:GridCommandState,) =>voidUpdates a retained element after its value, style, theme, or geometry changes.API reference →(gridconst grid: Gridconstgrid:Gridconstgrid:GridThe imperative core grid this controller owns.API reference →.getCommandStateGrid.getCommandState(command: GridCommandName): GridCommandStateGrid.getCommandState(command: GridCommandName): GridCommandStateGrid.getCommandState(command: GridCommandName): GridCommandStateQuery undo/redo availability and formatting active/mixed/disabled state.API reference →("bold"), gridconst grid: Gridconstgrid:Gridconstgrid:GridThe imperative core grid this controller owns.API reference →.getCommandStateGrid.getCommandState(command: GridCommandName): GridCommandStateGrid.getCommandState(command: GridCommandName): GridCommandStateGrid.getCommandState(command: GridCommandName): GridCommandStateQuery undo/redo availability and formatting active/mixed/disabled state.API reference →("undo"));
updateconst update: (bold: GridCommandState, undo: GridCommandState) => voidconstupdate: (bold:GridCommandState,undo:GridCommandState,) =>voidconstupdate: (bold:GridCommandState,undo:GridCommandState,) =>voidUpdates a retained element after its value, style, theme, or geometry changes.API reference →(statesstates: Readonly<Record<GridCommandName, GridCommandState>>let states:Readonly<Record<GridCommandName, GridCommandState>>let states:Readonly<Record<GridCommandName,GridCommandState>>.boldbold: GridCommandStatelet bold:GridCommandStatelet bold:GridCommandStateUses the bold variant of the theme font.API reference →, statesstates: Readonly<Record<GridCommandName, GridCommandState>>let states:Readonly<Record<GridCommandName, GridCommandState>>let states:Readonly<Record<GridCommandName,GridCommandState>>.undoundo: GridCommandStatelet undo:GridCommandStatelet undo:GridCommandStateUndo the last recorded cell edit.API reference →);
});
boldButtonconst boldButton: HTMLButtonElementconstboldButton:HTMLButtonElementconstboldButton:HTMLButtonElement.addEventListenerHTMLButtonElement.addEventListener<"click">(type: "click", listener: (this: HTMLButtonElement, ev: PointerEvent) => any, options?: boolean | AddEventListenerOptions): void (+1 overload)HTMLButtonElement.addEventListener<"click">(type: "click", listener: (this:HTMLButtonElement, ev:PointerEvent) => any, options?: boolean | AddEventListenerOptions): void (+1 overload)HTMLButtonElement.addEventListener<"click">(type: "click", listener: (this:HTMLButtonElement, ev:PointerEvent) => any, options?: boolean | AddEventListenerOptions): void (+1 overload)The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target. MDN Reference Adds a new handler for the type event. Any given listener is added only once per type and per capture option value. If the once option is true, the listener is removed after the next time a type event is dispatched. The capture option is not used by Node.js in any functional way other than tracking registered event listeners per the EventTarget specification. Specifically, the capture option is used as part of the key when registering a listener. Any individual listener may be added once with capture = false, and once with capture = true. The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target. MDN Reference Adds a new handler for the type event. Any given listener is added only once per type and per capture option value. If the once option is true, the listener is removed after the next time a type event is dispatched. The capture option is not used by Node.js in any functional way other than tracking registered event listeners per the EventTarget specification. Specifically, the capture option is used as part of the key when registering a listener. Any individual listener may be added once with capture = false, and once with capture = true.("click", () =>gridconst grid: Gridconstgrid:Gridconstgrid:GridThe imperative core grid this controller owns.API reference →.actionsGrid.actions: GridActionsinterfaceGrid {actions:GridActions;}interfaceGrid {actions:GridActions;}Imperative action surface for binding custom toolbars/menus.API reference →.toggleBoldGridActions.toggleBold(): voidGridActions.toggleBold(): voidGridActions.toggleBold(): voidAPI reference →());
undoButtonconst undoButton: HTMLButtonElementconstundoButton:HTMLButtonElementconstundoButton:HTMLButtonElement.addEventListenerHTMLButtonElement.addEventListener<"click">(type: "click", listener: (this: HTMLButtonElement, ev: PointerEvent) => any, options?: boolean | AddEventListenerOptions): void (+1 overload)HTMLButtonElement.addEventListener<"click">(type: "click", listener: (this:HTMLButtonElement, ev:PointerEvent) => any, options?: boolean | AddEventListenerOptions): void (+1 overload)HTMLButtonElement.addEventListener<"click">(type: "click", listener: (this:HTMLButtonElement, ev:PointerEvent) => any, options?: boolean | AddEventListenerOptions): void (+1 overload)The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target. MDN Reference Adds a new handler for the type event. Any given listener is added only once per type and per capture option value. If the once option is true, the listener is removed after the next time a type event is dispatched. The capture option is not used by Node.js in any functional way other than tracking registered event listeners per the EventTarget specification. Specifically, the capture option is used as part of the key when registering a listener. Any individual listener may be added once with capture = false, and once with capture = true. The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target. MDN Reference Adds a new handler for the type event. Any given listener is added only once per type and per capture option value. If the once option is true, the listener is removed after the next time a type event is dispatched. The capture option is not used by Node.js in any functional way other than tracking registered event listeners per the EventTarget specification. Specifically, the capture option is used as part of the key when registering a listener. Any individual listener may be added once with capture = false, and once with capture = true.("click", () =>gridconst grid: Gridconstgrid:Gridconstgrid:GridThe imperative core grid this controller owns.API reference →.actionsGrid.actions: GridActionsinterfaceGrid {actions:GridActions;}interfaceGrid {actions:GridActions;}Imperative action surface for binding custom toolbars/menus.API reference →.undoGridActions.undo(): voidGridActions.undo(): voidGridActions.undo(): voidUndo the last recorded cell edit.API reference →());
disabled accounts for read-only mode, empty selections, and undo/redo history.
Formatting commands report activity: "inactive" | "active" | "mixed" across
the current selection. The built-in toolbar uses the same contract, including
native disabled and aria-pressed="mixed". Aggregation is bounded; very large
selections conservatively report mixed rather than forcing an unbounded cell
walk.
Feature flags
Three GridConfig fields enable behavior that lives outside the toolbar row:
Field
Type
Default
Effect
find
boolean
true
Built-in Ctrl+F search box, next/previous controls, and live match count.
contextMenu
boolean | ContextMenuItems
true
Built-in right-click menu, disabled menu, static readonly rows, or a context-aware row factory.
icons
Partial<Record<ToolbarActionName, ToolbarIcon>>
undefined
Built-in toolbar icon overrides. Strings render as text; a DOM Node or () => Node supports SVG/HTML without innerHTML.
Context-menu items
The default menu contains copy, cut, paste, clear contents, row
insert/delete/hide/show/auto-fit, column insert/delete/hide/show/auto-fit,
clear column filter, merge, and unmerge actions, with separators between
groups. exportCsv and exportXlsx are also valid built-in actions in a
custom list.
ContextMenuItems is either a readonly ContextMenuItem[] or a factory
evaluated for each ContextMenuContext. An item may set a stable id,
built-in action, visible label, shortcut hint, and static or
context-aware visible/disabled policy. The lean context carries only
cell, clientX, and clientY. onClick(grid, cell) overrides action;
hidden separators are normalized.
visibleContextMenuItem.visible?: boolean | ((context: ContextMenuContext) => boolean) | undefinedinterfaceContextMenuItem {visible?:|boolean| ((context:ContextMenuContext) =>boolean)|undefined;}interfaceContextMenuItem {visible?:|boolean| ((context:ContextMenuContext,) =>boolean)|undefined;}Static or request-aware visibility. Hidden separators are normalized.API reference →: contextcontext: ContextMenuContextlet context:ContextMenuContextlet context:ContextMenuContextAPI reference →.cellContextMenuContext.cell: CellAddress | nullinterfaceContextMenuContext {cell:CellAddress|null;}interfaceContextMenuContext {cell:CellAddress|null;}Right-clicked cell, or null when the pointer is outside the cell body.API reference →!==null,
disabledContextMenuItem.disabled?: boolean | ((context: ContextMenuContext) => boolean) | undefinedinterfaceContextMenuItem {disabled?:|boolean| ((context:ContextMenuContext) =>boolean)|undefined;}interfaceContextMenuItem {disabled?:|boolean| ((context:ContextMenuContext,) =>boolean)|undefined;}Static or context-aware disabled state.API reference →: ({ cellcell: CellAddress | nulllet cell:CellAddress|nulllet cell:CellAddress|nullRight-clicked cell, or null when the pointer is outside the cell body.API reference → }) =>cellcell: CellAddress | nulllet cell:CellAddress|nulllet cell:CellAddress|nullRight-clicked cell, or null when the pointer is outside the cell body.API reference →===null,
onClickContextMenuItem.onClick?: ((grid: Grid, cell: CellAddress | null) => void) | undefinedinterfaceContextMenuItem {onClick?:((grid:Grid, cell:CellAddress|null) =>void) |undefined;}interfaceContextMenuItem {onClick?:| ((grid:Grid,cell:CellAddress|null,) =>void)|undefined;}Custom click handler; receives the grid and the right-clicked cell (null if none).API reference →(gridgrid: Gridlet grid:Gridlet grid:GridThe imperative core grid this controller owns.API reference →, cellcell: CellAddress | nulllet cell:CellAddress|nulllet cell:CellAddress|nullRight-clicked cell, or null when the pointer is outside the cell body.API reference →) {
if (cellcell: CellAddress | nulllet cell:CellAddress|nulllet cell:CellAddress|nullRight-clicked cell, or null when the pointer is outside the cell body.API reference →!==null) consolevar console: Consolevar console:Consolevar console:Console.logConsole.log(...data: any[]): void (+1 overload)Console.log(...data: any[]): void (+1 overload)Console.log(...data: any[]): void (+1 overload)The console.log() static method outputs a message to the console. MDN Reference(gridgrid: Gridlet grid:Gridlet grid:GridThe imperative core grid this controller owns.API reference →.storeGrid.store: StoreinterfaceGrid {store:Store;}interfaceGrid {store:Store;}.getCellStore.getCell(addr: CellAddress): ResolvedCellStore.getCell(addr: CellAddress): ResolvedCellStore.getCell(addr: CellAddress): ResolvedCellSingle-cell read for interactions, API reads, and tests. NOT for the render hot path — renderers use getVisibleWindow.API reference →(cellcell: CellAddresslet cell:CellAddresslet cell:CellAddressRight-clicked cell, or null when the pointer is outside the cell body.API reference →));
} satisfiesGridConfiginterface GridConfiginterfaceGridConfiginterfaceGridConfigToolbar / feature configuration. When config is set the built-in toolbar is shown; control flags default to true except the opt-in export flag.API reference →;
For fully host-owned UI, set contextMenu: false, listen for the DOM
contextmenu event on the host, call
grid.getCellAtPoint(event.clientX, event.clientY), update selection, and
invoke grid.actions from the host menu. Sheetwrite does not prescribe the
host's event lifecycle:
Host-owned context menu
hostconst host: HTMLElementconsthost:HTMLElementconsthost:HTMLElement.addEventListenerHTMLElement.addEventListener<"contextmenu">(type: "contextmenu", listener: (this: HTMLElement, ev: PointerEvent) => any, options?: boolean | AddEventListenerOptions): void (+1 overload)HTMLElement.addEventListener<"contextmenu">(type: "contextmenu", listener: (this:HTMLElement, ev:PointerEvent) => any, options?: boolean | AddEventListenerOptions): void (+1 overload)HTMLElement.addEventListener<"contextmenu">(type: "contextmenu", listener: (this:HTMLElement, ev:PointerEvent) => any, options?: boolean | AddEventListenerOptions): void (+1 overload)The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target. MDN Reference Adds a new handler for the type event. Any given listener is added only once per type and per capture option value. If the once option is true, the listener is removed after the next time a type event is dispatched. The capture option is not used by Node.js in any functional way other than tracking registered event listeners per the EventTarget specification. Specifically, the capture option is used as part of the key when registering a listener. Any individual listener may be added once with capture = false, and once with capture = true. The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target. MDN Reference Adds a new handler for the type event. Any given listener is added only once per type and per capture option value. If the once option is true, the listener is removed after the next time a type event is dispatched. The capture option is not used by Node.js in any functional way other than tracking registered event listeners per the EventTarget specification. Specifically, the capture option is used as part of the key when registering a listener. Any individual listener may be added once with capture = false, and once with capture = true.("contextmenu", (eventevent: PointerEventlet event:PointerEventlet event:PointerEvent) => {
eventevent: PointerEventlet event:PointerEventlet event:PointerEvent.preventDefaultEvent.preventDefault(): void (+1 overload)Event.preventDefault(): void (+1 overload)Event.preventDefault(): void (+1 overload)Sets the defaultPrevented property to true if cancelable is true.();
constcellconst cell: CellAddress | nullconstcell:CellAddress|nullconstcell:CellAddress|nullRight-clicked cell, or null when the pointer is outside the cell body.API reference →=gridconst grid: Gridconstgrid:Gridconstgrid:GridThe imperative core grid this controller owns.API reference →.getCellAtPointGrid.getCellAtPoint(clientX: number, clientY: number): CellAddress | nullGrid.getCellAtPoint(clientX: number, clientY: number): CellAddress |nullGrid.getCellAtPoint(clientX: number, clientY: number): CellAddress |nullResolve browser viewport coordinates to an active-sheet cell for host-owned menus and interactions. Returns null outside the cell body.API reference →(eventevent: PointerEventlet event:PointerEventlet event:PointerEvent.clientXMouseEvent.clientX: numberinterfaceMouseEvent {clientX:number;}interfaceMouseEvent {clientX:number;}The clientX read-only property of the MouseEvent interface provides the horizontal coordinate within the application's viewport at which the event occurred (as opposed to the coordinate within the page). MDN ReferenceAPI reference →, eventevent: PointerEventlet event:PointerEventlet event:PointerEvent.clientYMouseEvent.clientY: numberinterfaceMouseEvent {clientY:number;}interfaceMouseEvent {clientY:number;}The clientY read-only property of the MouseEvent interface provides the vertical coordinate within the application's viewport at which the event occurred (as opposed to the coordinate within the page). MDN ReferenceAPI reference →);
if (cellconst cell: CellAddress | nullconstcell:CellAddress|nullconstcell:CellAddress|nullRight-clicked cell, or null when the pointer is outside the cell body.API reference →!==null) gridconst grid: Gridconstgrid:Gridconstgrid:GridThe imperative core grid this controller owns.API reference →.setSelectionGrid.setSelection(sel: Selection | null): voidGrid.setSelection(sel: Selection |null): voidGrid.setSelection(sel: Selection |null): void({ kindkind: "cell"let kind:"cell"let kind:"cell"Selects one addressed cell.: "cell", addraddr: CellAddresslet addr:CellAddresslet addr:CellAddressZero-based data address of the selected cell.API reference →: cellconst cell: CellAddressconstcell:CellAddressconstcell:CellAddressRight-clicked cell, or null when the pointer is outside the cell body.API reference → });
hostconst host: HTMLElementconsthost:HTMLElementconsthost:HTMLElement.dispatchEventEventTarget.dispatchEvent(event: Event): boolean (+1 overload)EventTarget.dispatchEvent(event: Event): boolean (+1 overload)EventTarget.dispatchEvent(event: Event): boolean (+1 overload)Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.(
Undo/redo and find are keyboard-driven and work without the toolbar: Ctrl+Z
undoes the last edit, Ctrl+Shift+Z redoes it, and Ctrl+F opens the find
widget (unless find: false).
Grid instance
createGrid returns an imperative handle:
Partial example
interfaceGridinterface Grid
interface GridinterfaceGridinterfaceGridinterfaceGridinterfaceGridImperative grid handle for document commands, events, rendering, and teardown.API reference → {
readonlyactionsGrid.actions: GridActionsinterfaceGrid {actions:GridActions;}interfaceGrid {actions:GridActions;}Imperative action surface for binding custom toolbars/menus.API reference →:GridActionsinterface GridActionsinterfaceGridActionsinterfaceGridActionsImperative operations the toolbar and context menu bind to; also exposed as Grid.actions.API reference →;
setActiveSheetGrid.setActiveSheet(id: SheetId): voidGrid.setActiveSheet(id: SheetId): voidGrid.setActiveSheet(id: SheetId): void(idid: stringlet id:stringlet id:stringStable identity used by operations, history, and collaboration rebase.API reference →:SheetIdtype SheetId = stringtypeSheetId=string;typeSheetId=string;Stable identifier used to address a workbook sheet.API reference →):void;
scrollToCellGrid.scrollToCell(addr: CellAddress): voidGrid.scrollToCell(addr: CellAddress): voidGrid.scrollToCell(addr: CellAddress): void(addr:CellAddressinterface CellAddressinterfaceCellAddressinterfaceCellAddressZero-based address of one cell on a stable sheet ID.API reference →):void;
setThemeGrid.setTheme(theme: Partial<Theme>): voidGrid.setTheme(theme: Partial<Theme>): voidGrid.setTheme(theme: Partial<Theme>): voidImperative patch: merge theme into the accumulated base theme.API reference →(themetheme: Partial<Theme>let theme:Partial<Theme>let theme:Partial<Theme>Overrides merged over the default theme and host CSS custom properties.API reference →:Partialtype Partial<T> = { [P in keyof T]?: T[P] | undefined; }typePartial<T> = { [PinkeyofT]?:T[P] |undefined };typePartial<T> = {[PinkeyofT]?:T[P] |undefined;};Make all properties in T optional<Themeinterface ThemeinterfaceThemeinterfaceThemeResolved canvas colors, typography, and geometry used for painting.API reference →>):void;
defineCellRendererGrid.defineCellRenderer(name: string, renderer: CellRenderer): voidGrid.defineCellRenderer(name: string, renderer: CellRenderer): voidGrid.defineCellRenderer(name: string, renderer: CellRenderer): void(namename: stringlet name:stringlet name:stringUser-facing sheet name shown in tabs and workbook exports.API reference →:string, rendererrenderer: CellRendererlet renderer:CellRendererlet renderer:CellRendererName of a registered custom cell renderer (see Grid.defineCellRenderer).API reference →:CellRendererinterface CellRendererinterfaceCellRendererinterfaceCellRendererCustom cell renderer hooks for the main-thread canvas or retained DOM overlay.API reference →):void;
aggregateGrid.aggregate(col: number, op: AggregateOp): numberGrid.aggregate(col: number, op: AggregateOp): numberGrid.aggregate(col: number, op: AggregateOp): numberColumn aggregate over the active sheet's data.API reference →(col:number, op:AggregateOptype AggregateOp = "sum" | "avg" | "min" | "max" | "count"typeAggregateOp="sum"|"avg"|"min"|"max"|"count";typeAggregateOp=|"sum"|"avg"|"min"|"max"|"count";Column aggregate operation for Grid.aggregate / Store data ops.API reference →):number;
sortByGrid.sortBy(col: number, ascending?: boolean): voidGrid.sortBy(col: number, ascending?: boolean): voidGrid.sortBy(col: number, ascending?: boolean): voidSort the displayed rows by a column (does not mutate stored data).API reference →(col:number, ascendingascending: boolean | undefinedlet ascending:boolean|undefinedlet ascending:boolean|undefined?:boolean):void;
sortByMultiGrid.sortByMulti(keys: readonly SortKey[]): voidGrid.sortByMulti(keys: readonly SortKey[]): voidGrid.sortByMulti(keys: readonly SortKey[]): voidMulti-key sort of the displayed rows (first key primary; stable).API reference →(keyskeys: readonly SortKey[]let keys:readonlySortKey[]let keys:readonlySortKey[]Stable workbook column keys for every index in [start, end).API reference →:readonlySortKeyinterface SortKeyinterfaceSortKeyinterfaceSortKeyOne key of a multi-column sort, applied in array order (first = primary).API reference →[]):void;
filterByGrid.filterBy(col: number, needle: string): voidGrid.filterBy(col: number, needle: string): voidGrid.filterBy(col: number, needle: string): voidFilter the displayed rows to those whose column text contains needle.API reference →(col:number, needle:string):void;
setColumnFilterGrid.setColumnFilter(col: number, filter: ColumnFilter | null): voidGrid.setColumnFilter(col: number, filter: ColumnFilter |null): voidGrid.setColumnFilter(col: number, filter: ColumnFilter |null): voidSet or clear (null) one column's filter. All column filters AND together and compose with the active sort and hidden rows.API reference →(col:number, filter:ColumnFiltertype ColumnFilter = {
kind: "values";
values: readonly CellScalar[];
} | {
kind: "contains";
text: string;
matchCase?: boolean;
} | {
kind: "compare";
op: "gt" | "gte" | "lt" | "lte" | "eq" | "neq";
value: number;
} | {
kind: "empty";
} | {
kind: "nonEmpty";
}typeColumnFilter=| {kind:"values";values:readonlyCellScalar[];}| {kind:"contains";text:string;matchCase?:boolean;}| {kind:"compare";op:"gt"|"gte"|"lt"|"lte"|"eq"|"neq";value:number;}| {kind:"empty";}| {kind:"nonEmpty";};typeColumnFilter=| {kind:"values";values:readonlyCellScalar[];}| {kind:"contains";text:string;matchCase?:boolean;}| {kind:"compare";op:|"gt"|"gte"|"lt"|"lte"|"eq"|"neq";value:number;}| {kind:"empty";}| {kind:"nonEmpty";};One column's filter predicate. All active column filters AND together; matching is against the cell's resolved value (text or number).API reference →|null):void;
getColumnFiltersGrid.getColumnFilters(): ReadonlyMap<number, ColumnFilter>Grid.getColumnFilters(): ReadonlyMap<number, ColumnFilter>Grid.getColumnFilters(): ReadonlyMap<number, ColumnFilter>Active column filters on the active sheet, keyed by column index.API reference →():ReadonlyMapinterface ReadonlyMap<K, V>interfaceReadonlyMap<K, V>interfaceReadonlyMap<K, V><number, ColumnFiltertype ColumnFilter = {
kind: "values";
values: readonly CellScalar[];
} | {
kind: "contains";
text: string;
matchCase?: boolean;
} | {
kind: "compare";
op: "gt" | "gte" | "lt" | "lte" | "eq" | "neq";
value: number;
} | {
kind: "empty";
} | {
kind: "nonEmpty";
}typeColumnFilter=| {kind:"values";values:readonlyCellScalar[];}| {kind:"contains";text:string;matchCase?:boolean;}| {kind:"compare";op:"gt"|"gte"|"lt"|"lte"|"eq"|"neq";value:number;}| {kind:"empty";}| {kind:"nonEmpty";};typeColumnFilter=| {kind:"values";values:readonlyCellScalar[];}| {kind:"contains";text:string;matchCase?:boolean;}| {kind:"compare";op:|"gt"|"gte"|"lt"|"lte"|"eq"|"neq";value:number;}| {kind:"empty";}| {kind:"nonEmpty";};One column's filter predicate. All active column filters AND together; matching is against the cell's resolved value (text or number).API reference →>;
distinctValuesGrid.distinctValues(col: number, limit?: number): CellScalar[]Grid.distinctValues(col: number, limit?: number): CellScalar[]Grid.distinctValues(col: number, limit?: number): CellScalar[]Distinct resolved values of a column in first-seen order. Defaults to 1,000 values for bounded filter menus; pass 0 to request an uncapped scan.API reference →(col:number, limitlimit: number | undefinedlet limit:number|undefinedlet limit:number|undefined?:number):CellScalartype CellScalar = string | number | boolean | nulltypeCellScalar=string|number|boolean|null;typeCellScalar=|string|number|boolean|null;A scalar that can be displayed directly.API reference →[];
hideRowsGrid.hideRows(rows: readonly number[]): voidGrid.hideRows(rows: readonly number[]): voidGrid.hideRows(rows: readonly number[]): voidHide the given data rows (composes with filters/sort).API reference →(rowsrows: readonly number[]let rows:readonlynumber[]let rows:readonlynumber[]end-exclusive row rangeAPI reference →:readonlynumber[]):void;
showRowsGrid.showRows(rows?: readonly number[]): voidGrid.showRows(rows?: readonly number[]): voidGrid.showRows(rows?: readonly number[]): voidShow the given data rows again, or every hidden row when omitted.API reference →(rowsrows: readonly number[] | undefinedlet rows:readonlynumber[] |undefinedlet rows:readonlynumber[] |undefinedend-exclusive row rangeAPI reference →?:readonlynumber[]):void;
hiddenRowsGrid.hiddenRows(): readonly number[]Grid.hiddenRows(): readonly number[]Grid.hiddenRows(): readonly number[]Currently hidden data rows on the active sheet.API reference →():readonlynumber[];
hiddenColumnsGrid.hiddenColumns(): readonly number[]Grid.hiddenColumns(): readonly number[]Grid.hiddenColumns(): readonly number[]Currently hidden columns on the active sheet.API reference →():readonlynumber[];
groupRowsGrid.groupRows(start: number, end: number): voidGrid.groupRows(start: number, end: number): voidGrid.groupRows(start: number, end: number): voidDefine a collapsible row group over a data-row range (end-inclusive).API reference →(startstart: numberlet start:numberlet start:numberZero-based workbook column index of the first key.API reference →:number, endend: numberlet end:numberlet end:numberExclusive workbook column index after the last key.API reference →:number):void;
ungroupRowsGrid.ungroupRows(start: number, end: number): voidGrid.ungroupRows(start: number, end: number): voidGrid.ungroupRows(start: number, end: number): voidRemove a row group (rows become visible if the group was collapsed).API reference →(startstart: numberlet start:numberlet start:numberZero-based workbook column index of the first key.API reference →:number, endend: numberlet end:numberlet end:numberExclusive workbook column index after the last key.API reference →:number):void;
setGroupCollapsedGrid.setGroupCollapsed(start: number, collapsed: boolean): voidGrid.setGroupCollapsed(start: number, collapsed: boolean): voidGrid.setGroupCollapsed(start: number, collapsed: boolean): voidCollapse/expand a row group; collapsing hides its rows.API reference →(startstart: numberlet start:numberlet start:numberZero-based workbook column index of the first key.API reference →:number, collapsed:boolean):void;
rowGroupsGrid.rowGroups(): readonly RowGroup[]Grid.rowGroups(): readonly RowGroup[]Grid.rowGroups(): readonly RowGroup[]Row groups on the active sheet.API reference →():readonlyRowGroupinterface RowGroupinterfaceRowGroupinterfaceRowGroupA collapsible row group (data-row range, end-inclusive), Sheets-style.API reference →[];
clearViewGrid.clearView(): voidGrid.clearView(): voidGrid.clearView(): voidClear any active sort/filter view.API reference →():void;
undoGrid.undo(): voidGrid.undo(): voidGrid.undo(): voidUndo the last recorded cell edit.API reference →():void;
redoGrid.redo(): voidGrid.redo(): voidGrid.redo(): voidRedo the last undone cell edit.API reference →():void;
exportXlsxGrid.exportXlsx(filename: string): Promise<void>Grid.exportXlsx(filename: string): Promise<void>Grid.exportXlsx(filename: string): Promise<void>API reference →(filename:string):Promiseinterface Promise<T>interfacePromise<T>interfacePromise<T>Represents the completion of an asynchronous operation<void>;
searchGrid.search(query: string, opts?: SearchOptions): SearchResultGrid.search(query: string, opts?: SearchOptions): SearchResultGrid.search(query: string, opts?: SearchOptions): SearchResultFind cells matching query; highlights matches, emits search, returns the result.API reference →(queryquery: stringlet query:stringlet query:stringQuery string retained for navigation and subsequent replacement.API reference →:string, optsopts: SearchOptions | undefinedlet opts:SearchOptions|undefinedlet opts:SearchOptions|undefinedAPI reference →?:SearchOptionsinterface SearchOptionsinterfaceSearchOptionsinterfaceSearchOptionsCase, whole-cell, sheet, and column constraints for grid search.API reference →):SearchResultinterface SearchResultinterfaceSearchResultinterfaceSearchResultOrdered matches and active index produced by a grid search.API reference →;
findNextGrid.findNext(): SearchResultGrid.findNext(): SearchResultGrid.findNext(): SearchResultMove the active match to the next match and scroll it into view.API reference →():SearchResultinterface SearchResultinterfaceSearchResultinterfaceSearchResultOrdered matches and active index produced by a grid search.API reference →;
findPrevGrid.findPrev(): SearchResultGrid.findPrev(): SearchResultGrid.findPrev(): SearchResultMove the active match to the previous match and scroll it into view.API reference →():SearchResultinterface SearchResultinterfaceSearchResultinterfaceSearchResultOrdered matches and active index produced by a grid search.API reference →;
clearSearchGrid.clearSearch(): voidGrid.clearSearch(): voidGrid.clearSearch(): voidClear the current search and its highlights.API reference →():void;
replaceCurrentGrid.replaceCurrent(replacement: string): SearchResultGrid.replaceCurrent(replacement: string): SearchResultGrid.replaceCurrent(replacement: string): SearchResultReplace the active match with replacement, then advance to the next match (re-scanning against the new data). Only literal text/number cells are eligible; formula and ref cells are skipped (formula source is never rewritten). Honors the active SearchOptions (matchCase; wholeCell swaps the entire cell). The write flows through the grid's commit path as one undoable step. No-op when read-only or when there is no active match.API reference →(replacement:string):SearchResultinterface SearchResultinterfaceSearchResultinterfaceSearchResultOrdered matches and active index produced by a grid search.API reference →;
replaceAllGrid.replaceAll(replacement: string): ReplaceResultGrid.replaceAll(replacement: string): ReplaceResultGrid.replaceAll(replacement: string): ReplaceResultReplace every current match in a single undoable transaction (one undo() restores them all), then re-scan. Formula/ref cells are skipped and not counted. No-op when read-only.API reference →(replacement:string):ReplaceResultinterface ReplaceResultinterfaceReplaceResultinterfaceReplaceResultReplacement count and refreshed search state returned by replace-all.API reference →;
highlightCellsGrid.highlightCells(ranges: readonly HighlightRange[] | null, color?: string): voidGrid.highlightCells(ranges: readonly HighlightRange[] |null, color?: string): voidGrid.highlightCells(ranges: readonly HighlightRange[] |null, color?: string): voidHighlight arbitrary cell ranges (null clears). Per-range color wins over the call color.API reference →(ranges:readonlyHighlightRangeinterface HighlightRangeinterfaceHighlightRangeinterfaceHighlightRangeA highlight target: a range plus an optional per-range color override.API reference →[] |null, colorcolor: string | undefinedlet color:string|undefinedlet color:string|undefinedhex color, e.g. "#111111"API reference →?:string):void;
styleRangeGrid.styleRange(range: Range, style: Partial<CellStyle> | null): voidGrid.styleRange(range: Range, style: Partial<CellStyle>|null): voidGrid.styleRange(range: Range, style: Partial<CellStyle>|null): voidMerge style into every cell of range (null clears cell styles) as one undoable transaction. Styles land in the store and paint in the canvas — unlike highlightCells, which draws a translucent overlay above it.API reference →(rangerange: Rangelet range:Rangelet range:RangeInclusive table rectangle on one stable sheet ID.API reference →:Rangeinterface RangeinterfaceRangeinterfaceRangeThe Range interface represents a fragment of a document that can contain nodes and parts of text nodes. MDN ReferenceAPI reference →, stylestyle: Partial<CellStyle> | nulllet style:Partial<CellStyle> |nulllet style:Partial<CellStyle> |nullOptional override merged over the deterministic blue/underline link style.API reference →:Partialtype Partial<T> = { [P in keyof T]?: T[P] | undefined; }typePartial<T> = { [PinkeyofT]?:T[P] |undefined };typePartial<T> = {[PinkeyofT]?:T[P] |undefined;};Make all properties in T optional<CellStyleinterface CellStyleinterfaceCellStyleinterfaceCellStyleSerializable formatting applied to a cell or used as a column default.API reference →> |null):void;
dataEdgeGrid.dataEdge(row: number, col: number, dRow: number, dCol: number): number | nullGrid.dataEdge(row: number, col: number, dRow: number, dCol: number): number |nullGrid.dataEdge(row: number, col: number, dRow: number, dCol: number): number |nullCtrl+Arrow-style jump target: the data-run edge from (row, col) on the moved axis (row for vertical moves, col for horizontal), or null when the store is not columnar. Under an active sort/filter view, row is a view position and vertical moves return view positions. For hosts building their own keymaps (config.keyboard).API reference →(row:number, col:number, dRow:number, dCol:number):number|null;
setRowHeightGrid.setRowHeight(row: number, height: number): voidGrid.setRowHeight(row: number, height: number): voidGrid.setRowHeight(row: number, height: number): voidSet one row's persistent display height through document history.API reference →(row:number, heightheight: numberlet height:numberlet height:numberHost height in CSS pixels for numbers or any CSS length string.API reference →:number):void;
setColumnWidthGrid.setColumnWidth(col: number, width: number): voidGrid.setColumnWidth(col: number, width: number): voidGrid.setColumnWidth(col: number, width: number): voidSet one column's width via an undoable setColumn patch.API reference →(col:number, widthwidth: numberlet width:numberlet width:numberUnzoomed column width in CSS pixels.API reference →:number):void;
autoFitRowsGrid.autoFitRows(range?: Range): voidGrid.autoFitRows(range?: Range): voidGrid.autoFitRows(range?: Range): voidExplicitly resize rows to fit wrapped content; never runs during paint.API reference →(rangerange: Range | undefinedlet range:Range|undefinedlet range:Range|undefinedInclusive table rectangle on one stable sheet ID.API reference →?:Rangeinterface RangeinterfaceRangeinterfaceRangeThe Range interface represents a fragment of a document that can contain nodes and parts of text nodes. MDN ReferenceAPI reference →):void;
setFrozenGrid.setFrozen(rows: number, cols?: number): voidGrid.setFrozen(rows: number, cols?: number): voidGrid.setFrozen(rows: number, cols?: number): voidPin the first rows view rows and cols columns; they stay visible while the body scrolls (0 = unfreeze that axis). Persisted on the active sheet.API reference →(rowsrows: numberlet rows:numberlet rows:numberend-exclusive row rangeAPI reference →:number, colscols: number | undefinedlet cols:number|undefinedlet cols:number|undefinedvisible column indices, in paint orderAPI reference →?:number):void;
destroyGrid.destroy(): voidGrid.destroy(): voidGrid.destroy(): voidRuns immediately before a retained element is removed or replaced.API reference →():void;
}
Method
Purpose
store
The underlying Store — apply transactions, read cells, subscribe.
actions
Imperative action surface (toggleBold(), merge(), undo(), exportCsv(), …) the toolbar and context menu bind to — use it to wire custom controls.
setActiveSheet(id)
Switch the visible sheet.
scrollToCell(addr)
Scroll a cell into view.
getSelection() / setSelection(sel)
Read or set the current Selection (null clears it).
Define protected-range metadata and host-owned local permission policy. This is not server authorization.
setNote / getNote
Set, clear, or read a serializable plain-text cell note.
beginEdit(row, col, initial?, selectAll?)
Open the inline editor at a view cell.
dataEdge(row, col, dRow, dCol)
Ctrl+Arrow-style data-run jump target; vertical movement is view-aware under sort/filter.
setRowHeight(row, h) / setColumnWidth(col, w)
Geometry APIs; row height is view-indexed and persists against the underlying data row.
autoFitRows(range?) / autoFitColumns(cols?)
Explicit, undoable geometry fitting from bulk reads; auto-fit never runs during paint.
on(evt, fn)
Subscribe to an event; returns an unsubscribe function.
refresh()
Force a re-render (e.g. after mutating the workbook directly).
destroy()
Tear down listeners, DOM, and ARIA attributes.
Search
grid.search(query, opts?) scans cells, highlights every match, scrolls the first
match into view, and emits a search event. findNext() / findPrev()
move the active match; clearSearch() clears the highlights. The built-in Ctrl+F
find widget (gated by config.find, on by default) drives this same API.
Partial example
interfaceSearchOptionsinterface SearchOptions
interface SearchOptionsinterfaceSearchOptionsinterfaceSearchOptionsinterfaceSearchOptionsinterfaceSearchOptionsCase, whole-cell, sheet, and column constraints for grid search.API reference → {
matchCaseSearchOptions.matchCase?: boolean | undefinedinterfaceSearchOptions {matchCase?:boolean|undefined;}interfaceSearchOptions {matchCase?:boolean|undefined;}Case-sensitive match (default false).API reference →?:boolean; // case-sensitive match (default false)
wholeCellSearchOptions.wholeCell?: boolean | undefinedinterfaceSearchOptions {wholeCell?:boolean|undefined;}interfaceSearchOptions {wholeCell?:boolean|undefined;}Match only when the whole cell text equals the query (default false: substring).API reference →?:boolean; // match the whole cell, not a substring (default false)
sheetSearchOptions.sheet?: string | undefinedinterfaceSearchOptions {sheet?:string|undefined;}interfaceSearchOptions {sheet?:string|undefined;}Sheet identity used by the simple data-first adapter. Defaults to sheet1.API reference →?:SheetIdtype SheetId = stringtypeSheetId=string;typeSheetId=string;Stable identifier used to address a workbook sheet.API reference →; // restrict to one sheet (default: the active sheet)
columnsSearchOptions.columns?: number[] | undefinedinterfaceSearchOptions {columns?:number[] |undefined;}interfaceSearchOptions {columns?:number[] |undefined;}Exact column runs represented by every returned row.API reference →?:number[]; // restrict to these column indices (default: all)
}
interfaceSearchResultinterface SearchResult
interface SearchResultinterfaceSearchResultinterfaceSearchResultinterfaceSearchResultinterfaceSearchResultOrdered matches and active index produced by a grid search.API reference → {
querySearchResult.query: stringinterfaceSearchResult {query:string;}interfaceSearchResult {query:string;}Query string retained for navigation and subsequent replacement.API reference →:string;
matchesSearchResult.matches: CellAddress[]interfaceSearchResult {matches:CellAddress[];}interfaceSearchResult {matches:CellAddress[];}Matching cells in row-major order.API reference →:CellAddressinterface CellAddressinterfaceCellAddressinterfaceCellAddressZero-based address of one cell on a stable sheet ID.API reference →[]; // matching cells, in row-major order
activeSearchResult.active: numberinterfaceSearchResult {active:number;}interfaceSearchResult {active:number;}Index of the active match within matches, or -1 when there are none.API reference →:number; // index of the active match, or -1 when there are none
}
Partial example
constresultconst result: SearchResultconstresult:SearchResultconstresult:SearchResultSearch state after the replacement (matches re-scanned against the new data).API reference →=gridconst grid: Gridconstgrid:Gridconstgrid:GridThe imperative core grid this controller owns.API reference →.searchGrid.search(query: string, opts?: SearchOptions): SearchResultGrid.search(query: string, opts?: SearchOptions): SearchResultGrid.search(query: string, opts?: SearchOptions): SearchResultFind cells matching query; highlights matches, emits search, returns the result.API reference →("error");
consolevar console: Consolevar console:Consolevar console:Console.logConsole.log(...data: any[]): void (+1 overload)Console.log(...data: any[]): void (+1 overload)Console.log(...data: any[]): void (+1 overload)The console.log() static method outputs a message to the console. MDN Reference(`${resultconst result: SearchResultconstresult:SearchResultconstresult:SearchResultSearch state after the replacement (matches re-scanned against the new data).API reference →.matchesSearchResult.matches: CellAddress[]interfaceSearchResult {matches:CellAddress[];}interfaceSearchResult {matches:CellAddress[];}Matching cells in row-major order.API reference →.lengthArray<CellAddress>.length: numberinterfaceArray<CellAddress> {length:number;}interfaceArray<CellAddress> {length:number;}Gets or sets the length of the array. This is a number one higher than the highest index in the array.API reference →} match(es)`);
gridconst grid: Gridconstgrid:Gridconstgrid:GridThe imperative core grid this controller owns.API reference →.findNextGrid.findNext(): SearchResultGrid.findNext(): SearchResultGrid.findNext(): SearchResultMove the active match to the next match and scroll it into view.API reference →(); // advance the active match and scroll to it
gridconst grid: Gridconstgrid:Gridconstgrid:GridThe imperative core grid this controller owns.API reference →.clearSearchGrid.clearSearch(): voidGrid.clearSearch(): voidGrid.clearSearch(): voidClear the current search and its highlights.API reference →(); // remove the highlights when done
highlightCells(ranges, color?) highlights arbitrary ranges independently of
search (pass null to clear); color overrides the theme highlight color.
Events
grid.on(evt, fn) returns an off() you should call to unsubscribe.
syncconst sync: SyncCoordinatorconstsync:SyncCoordinatorconstsync:SyncCoordinatorAPI reference →.destroySyncCoordinator.destroy(): voidSyncCoordinator.destroy(): voidSyncCoordinator.destroy(): voidRuns immediately before a retained element is removed or replaced.API reference →();