On this page createGrid returns an imperative Grid handle. Use it to read and change the document, the selection, the view and the layout.
grid . sortBy ( 1 , false ); // display-only sort, largest first
A B C 1 Desk 300 2 Chair 120 3 Lamp 40 4
Result: costs are displayed largest first, with Desk at the top. The first view row is frozen and the live grid is zoomed to 125%.
Usage example (requires an initialized grid)
This API excerpt needs an initialized grid with a text item column and a numeric cost column. Use these data rows in order: Lamp / 40, Desk / 300, Chair / 120. There is no header row in the cell data.
grid . sortBy ( 1 , false ); // display-only sort, largest first
The grid shows column B sorted from largest to smallest, the first row stays in place while the body scrolls, and content is drawn at 125%.
Each name in the tables links to its entry in the Grid API reference . These are the signatures of the methods on this page:
sortBy ( col : number , ascending ?: boolean ) : void ; beginEdit ( row : number , col : number , initial ?: string , selectAll ?: boolean ) : void ; dataEdge ( row : number , col : number , dRow : number , dCol : number ) : number | null ; // Also covered under "Other methods" below:
Document and sheets
Method Purpose storeThe underlying Store : apply transactions, read cells, subscribe. actionsImperative 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. undo() / redo()Undo or redo the last recorded cell edit (also bound to Ctrl+Z / Ctrl+Shift+Z). insertRows(at, count?) / removeRows(at, count?) / insertColumns(at, count?) / removeColumns(at, count?)Structural edits through undoable patches. styleRange(range, style)Merge or clear (null) store-backed cell styles across a range. setValidationRule(rule) / removeValidationRule(id)Add, replace, or remove a serializable range validation rule. List and checkbox rules get accessible editors. setProtectedRange(range) / removeProtectedRange(id) / setProtectionResolver(resolver?, mode?)Define protected-range metadata and host-owned local permission policy. This is not server authorization. setNote(addr, text) / getNote(addr)Set, clear (null), or read a serializable plain-text cell note. exportCsv(filename) / exportXlsx(filename)Download the active data; exportXlsx returns a promise. See Data operations .
Selection, editing and search
Method Purpose getSelection() / setSelection(sel)Read or set the current Selection (null clears it). scrollToCell(addr)Scroll a cell into view. 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, or null; vertical movement is view-aware under sort/filter. search(query, opts?)Find matching cells; highlights them, emits search, returns a SearchResult . findNext() / findPrev()Step the active match forward / backward and scroll it into view. clearSearch()Drop the current search and clear its highlights. replaceCurrent(replacement) / replaceAll(replacement)Replace literal text/number matches through undoable transactions. highlightCells(ranges, color?)Highlight arbitrary ranges (null clears); color overrides the theme highlight.
Views: sort, filter, hide and group
Method Purpose aggregate(col, op)Column aggregate (returns a number); see Data operations . sortBy(col, ascending?) / sortByMulti(keys)Non-mutating display sorts; see Data operations . filterBy(col, needle) / setColumnFilter(col, filter) / getColumnFilters()Column filters that compose with sort, hidden rows, and row groups. setColumnFilter(col, null) removes one. distinctValues(col, limit?)First-seen distinct values for building filter menus. hideRows(rows) / showRows(rows?) / hiddenRows()Explicit row visibility separate from sort/filter state. hideColumns(cols?) / showColumns(cols?) / hiddenColumns()Bulk-safe persisted column visibility; omitted arguments target the focused column for hide and every column for show. groupRows(start, end) / ungroupRows(start, end) / setGroupCollapsed(start, collapsed) / rowGroups()Inclusive data-row groups with collapse state. clearView()Clears sort/filter state; hidden rows and row groups remain.
Layout and appearance
Lifecycle
Method Purpose on(evt, fn)Subscribe to an event ; returns an unsubscribe function. refresh()Force a re-render, for example after mutating the workbook directly. destroy()Tear down listeners, DOM, and ARIA attributes.
Other methods
Edge cases and limits
Undo history keeps at most 200 entries. It also drops its oldest entries once retained range snapshots pass 256 MiB, about twenty million-cell clears. The newest entry always stays undoable.
The 256 MiB policy counts engine-reported snapshot bytes, not total process memory. Cloned formula ASTs and JavaScript patch/redo payloads are bounded only by the 200-entry limit.
Undo of a large clear restores the saved range directly from a packed engine snapshot.
Display sorts and filters do not change the document. clearView() keeps hidden rows and row groups.
See also
const sheet: string const sheet : string const sheet : string Sheet identity used by the simple data-first adapter. Defaults to sheet1. API reference → const grid: Grid const grid : Grid const grid : Grid The imperative core grid this controller owns. API reference → Grid.getActiveSheet(): SheetId Grid. getActiveSheet (): SheetId Grid. getActiveSheet (): SheetId Id of the currently visible sheet. API reference → Grid.setSelection(sel: Selection | null): void Grid. setSelection (sel: Selection | null ): void Grid. setSelection (sel: Selection | null ): void kind: "cell" let kind : "cell" let kind : "cell" Selects one addressed cell. addr: CellAddress let addr : CellAddress let addr : CellAddress Zero-based data address of the selected cell. API reference → CellAddress.sheet: string interface CellAddress {
sheet : string ;
} interface CellAddress {
sheet : string ;
} Sheet identity used by the simple data-first adapter. Defaults to sheet1. API reference → CellAddress.row: number interface CellAddress {
row : number ;
} interface CellAddress {
row : number ;
} 0-based row of the cell that holds the top-left corner. API reference → CellAddress.col: number interface CellAddress {
col : number ;
} interface CellAddress {
col : number ;
} 0-based column of the cell that holds the top-left corner. API reference → Grid.sortBy(col: number, ascending?: boolean): void Grid. sortBy (col: number, ascending ?: boolean): void Grid. sortBy (col: number, ascending ?: boolean): void Sort the displayed rows by a column (does not mutate stored data). Example import type { Grid } from "@sheetwrite/core" ;
function showLargestFirst ( grid : Grid ) {
grid. sortBy ( 1 , false );
} See also Grid.clearView API reference → Grid.setFrozen(rows: number, cols?: number): void Grid. setFrozen (rows: number, cols ?: number): void Grid. setFrozen (rows: number, cols ?: number): void Pin 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 → Grid.setZoom(zoom: number): void Grid. setZoom (zoom: number): void Grid. setZoom (zoom: number): void Content zoom factor (0.5–2): scales row/column geometry and fonts. API reference → var console: Console var console : Console var console : Console Console.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 Grid.getZoom(): number Grid. getZoom (): number Grid. getZoom (): number API reference → const off: () => void const off : () => void const off : () => void Grid.on<"selection">(evt: "selection", fn: (e: {
selection: Selection | null;
}) => void): () => void Grid. on < "selection" >(evt: "selection" , fn: ( e : {
selection : Selection | null ;
}) => void ): () => void Grid. on < "selection" >(evt: "selection" , fn: ( e : {
selection : Selection | null ;
}) => void ): () => void selection: Selection | null let selection : Selection | null let selection : Selection | null CSS color painted over the selected region. API reference → interface Grid
interface Grid interface Grid
interface Grid interface Grid
interface Grid Imperative grid handle for document commands, events, rendering, and teardown. Example import type { Grid } from "@sheetwrite/core" ;
function updateTotal ( grid : Grid ) {
const sheet = grid. getActiveSheet ();
const result = grid. applyTransaction ({
patches: [{ op: "set" , addr: { sheet, row: 0 , col: 0 }, value: { kind: "literal" , value: 42 } }],
});
if (result.status === "applied" ) grid. scrollToCell ({ sheet, row: 0 , col: 0 });
return grid. aggregate ( 0 , "sum" );
} See also createGrid * See also Grid.applyTransaction API reference → Grid.store: Store interface Grid {
store : Store ;
} interface Grid {
store : Store ;
} interface Store interface Store interface Store Columnar workbook storage, query, transaction, and subscription contract. API reference → Grid.actions: GridActions interface Grid {
actions : GridActions ;
} interface Grid {
actions : GridActions ;
} Imperative action surface for binding custom toolbars/menus. API reference → interface GridActions interface GridActions interface GridActions Imperative operations the toolbar and context menu bind to; also exposed as Grid.actions. API reference → Grid.setActiveSheet(id: SheetId): void Grid. setActiveSheet (id: SheetId): void Grid. setActiveSheet (id: SheetId): void id: string let id : string let id : string Stable identity used by operations, history, and collaboration rebase. API reference → type SheetId = string type SheetId = string ; type SheetId = string ; Stable identifier used to address a workbook sheet. API reference → Grid.scrollToCell(addr: CellAddress): void Grid. scrollToCell (addr: CellAddress): void Grid. scrollToCell (addr: CellAddress): void interface CellAddress interface CellAddress interface CellAddress Zero-based address of one cell on a stable sheet ID. API reference → Grid.getSelection(): Selection | null Grid. getSelection (): Selection | null Grid. getSelection (): Selection | null type Selection = {
kind: "cell";
addr: CellAddress;
} | {
kind: "range";
range: Range;
} | {
kind: "row";
sheet: SheetId;
row: number;
} | {
kind: "column";
sheet: SheetId;
col: number;
} | {
kind: "multi";
ranges: Range[];
} type Selection =
| {
kind : "cell" ;
addr : CellAddress ;
}
| {
kind : "range" ;
range : Range ;
}
| {
kind : "row" ;
sheet : SheetId ;
row : number ;
}
| {
kind : "column" ;
sheet : SheetId ;
col : number ;
}
| {
kind : "multi" ;
ranges : Range [];
}; type Selection =
| {
kind : "cell" ;
addr : CellAddress ;
}
| {
kind : "range" ;
range : Range ;
}
| {
kind : "row" ;
sheet : SheetId ;
row : number ;
}
| {
kind : "column" ;
sheet : SheetId ;
col : number ;
}
| {
kind : "multi" ;
ranges : Range [];
}; Current cell, range, row, column, or multi-range selection. API reference → Grid.setTheme(theme: Partial<Theme>): void Grid. setTheme (theme: Partial < Theme > ): void Grid. setTheme (theme: Partial < Theme > ): void Imperative patch: merge theme into the accumulated base theme. API reference → theme: Partial<Theme> let theme : Partial < Theme > let theme : Partial < Theme > Overrides merged over the default theme and host CSS custom properties. API reference → type Partial<T> = { [P in keyof T]?: T[P] | undefined; } type Partial < T > = { [ P in keyof T ] ?: T [ P ] | undefined }; type Partial < T > = {
[ P in keyof T ] ?:
T [ P ] | undefined ;
}; Make all properties in T optional interface Theme interface Theme interface Theme Resolved canvas colors, typography, and geometry used for painting. API reference → Grid.defineCellRenderer(name: string, renderer: CellRenderer): void Grid. defineCellRenderer (name: string, renderer: CellRenderer): void Grid. defineCellRenderer (name: string, renderer: CellRenderer): void name: string let name : string let name : string User-facing caption. API reference → renderer: CellRenderer let renderer : CellRenderer let renderer : CellRenderer Name of a registered custom cell renderer (see Grid.defineCellRenderer). API reference → interface CellRenderer interface CellRenderer interface CellRenderer Custom cell renderer hooks for the main-thread canvas or retained DOM overlay. API reference → Grid.aggregate(col: number, op: AggregateOp): number Grid. aggregate (col: number, op: AggregateOp): number Grid. aggregate (col: number, op: AggregateOp): number Column aggregate over the active sheet's data. @example import type { Grid } from "@sheetwrite/core"; function total(grid: Grid) { return grid.aggregate(1, "sum"); } @see SheetwriteStore.aggregate API reference → col: number let col : number let col : number 0-based column of the cell that holds the top-left corner. API reference → type AggregateOp = "sum" | "avg" | "min" | "max" | "count" type AggregateOp = "sum" | "avg" | "min" | "max" | "count" ; type AggregateOp =
| "sum"
| "avg"
| "min"
| "max"
| "count" ; Column aggregate operation for Grid.aggregate / Store data ops. API reference → Grid.sortBy(col: number, ascending?: boolean): void Grid. sortBy (col: number, ascending ?: boolean): void Grid. sortBy (col: number, ascending ?: boolean): void Sort the displayed rows by a column (does not mutate stored data). @example import type { Grid } from "@sheetwrite/core"; function showLargestFirst(grid: Grid) { grid.sortBy(1, false); } @see Grid.clearView API reference → ascending: boolean | undefined let ascending : boolean | undefined let ascending :
boolean | undefined Grid.sortByMulti(keys: readonly SortKey[]): void Grid. sortByMulti (keys: readonly SortKey[]): void Grid. sortByMulti (keys: readonly SortKey[]): void Multi-key sort of the displayed rows (first key primary; stable). API reference → keys: readonly SortKey[] let keys : readonly SortKey [] let keys : readonly SortKey [] Stable workbook column keys for every index in [start, end). API reference → interface SortKey interface SortKey interface SortKey One key of a multi-column sort, applied in array order (first = primary). API reference → Grid.filterBy(col: number, needle: string): void Grid. filterBy (col: number, needle: string): void Grid. filterBy (col: number, needle: string): void Filter the displayed rows to those whose column text contains needle. @example import type { Grid } from "@sheetwrite/core"; function showOpenRows(grid: Grid) { grid.filterBy(0, "Open"); } @see Grid.clearView API reference → Grid.setColumnFilter(col: number, filter: ColumnFilter | null): void Grid. setColumnFilter (col: number, filter: ColumnFilter | null ): void Grid. setColumnFilter (col: number, filter: ColumnFilter | null ): void Set or clear (null) one column's filter. All column filters AND together and compose with the active sort and hidden rows. API reference → type 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";
} type 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" ;
}; type 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" ;
}; One column's filter predicate. All active column filters AND together; matching is against the cell's resolved value (text or number). API reference → Grid.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 → interface ReadonlyMap<K, V> interface ReadonlyMap < K , V > interface ReadonlyMap < K , V > Grid.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 → limit: number | undefined let limit : number | undefined let limit :
number | undefined type CellScalar = string | number | boolean | null type CellScalar = string | number | boolean | null ; type CellScalar =
| string
| number
| boolean
| null ; A scalar that can be displayed directly. API reference → Grid.hideRows(rows: readonly number[]): void Grid. hideRows (rows: readonly number[]): void Grid. hideRows (rows: readonly number[]): void Hide the given data rows (composes with filters/sort). API reference → rows: readonly number[] let rows : readonly number [] let rows : readonly number [] Source field indices that group the output rows, outermost first. API reference → Grid.showRows(rows?: readonly number[]): void Grid. showRows (rows ?: readonly number[]): void Grid. showRows (rows ?: readonly number[]): void Show the given data rows again, or every hidden row when omitted. API reference → rows: readonly number[] | undefined let rows : readonly number [] | undefined let rows :
readonly number [] | undefined Source field indices that group the output rows, outermost first. API reference → Grid.hiddenRows(): readonly number[] Grid. hiddenRows (): readonly number[] Grid. hiddenRows (): readonly number[] Currently hidden data rows on the active sheet. API reference → Grid.hideColumns(cols?: readonly number[]): void Grid. hideColumns (cols ?: readonly number[]): void Grid. hideColumns (cols ?: readonly number[]): void Hide columns through one bulk-safe metadata transaction. API reference → cols: readonly number[] | undefined let cols : readonly number [] | undefined let cols :
readonly number [] | undefined visible column indices, in paint order API reference → Grid.showColumns(cols?: readonly number[]): void Grid. showColumns (cols ?: readonly number[]): void Grid. showColumns (cols ?: readonly number[]): void Show columns through one bulk-safe metadata transaction. API reference → Grid.hiddenColumns(): readonly number[] Grid. hiddenColumns (): readonly number[] Grid. hiddenColumns (): readonly number[] Currently hidden columns on the active sheet. API reference → Grid.groupRows(start: number, end: number): void Grid. groupRows (start: number, end: number): void Grid. groupRows (start: number, end: number): void Define a collapsible row group over a data-row range (end-inclusive). API reference → start: number let start : number let start : number Zero-based workbook column index of the first key. API reference → end: number let end : number let end : number Exclusive workbook column index after the last key. API reference → Grid.ungroupRows(start: number, end: number): void Grid. ungroupRows (start: number, end: number): void Grid. ungroupRows (start: number, end: number): void Remove a row group (rows become visible if the group was collapsed). API reference → Grid.setGroupCollapsed(start: number, collapsed: boolean): void Grid. setGroupCollapsed (start: number, collapsed: boolean): void Grid. setGroupCollapsed (start: number, collapsed: boolean): void Collapse/expand a row group; collapsing hides its rows. API reference → Grid.rowGroups(): readonly RowGroup[] Grid. rowGroups (): readonly RowGroup[] Grid. rowGroups (): readonly RowGroup[] Row groups on the active sheet. API reference → interface RowGroup interface RowGroup interface RowGroup A collapsible row group (data-row range, end-inclusive), Sheets-style. API reference → Grid.clearView(): void Grid. clearView (): void Grid. clearView (): void Clear any active sort/filter view. API reference → Grid.undo(): void Grid. undo (): void Grid. undo (): void Undo the last recorded cell edit. If the restored data is above the transaction resource limits, nothing changes: the Grid emits mutation-rejected and removes that entry, so older edits stay undoable. @example import type { Grid } from "@sheetwrite/core"; function undoAndRestore(grid: Grid) { grid.undo(); grid.redo(); } @see Grid.redo API reference → Grid.redo(): void Grid. redo (): void Grid. redo (): void Redo the last undone cell edit. API reference → Grid.exportCsv(filename: string): void Grid. exportCsv (filename: string): void Grid. exportCsv (filename: string): void Download the active sheet as CSV. @example import type { Grid } from "@sheetwrite/core"; function downloadCsv(grid: Grid) { grid.exportCsv("sales.csv"); } API reference → Grid.exportXlsx(filename: string): Promise<void> Grid. exportXlsx (filename: string): Promise <void> Grid. exportXlsx (filename: string): Promise <void> Download the active sheet through the registered XLSX backend. @example import type { Grid } from "@sheetwrite/core"; import { registerXlsxBackends } from "@sheetwrite/xlsx"; async function downloadXlsx(grid: Grid) { await registerXlsxBackends(); await grid.exportXlsx("sales.xlsx"); } @see toXlsxWorkbook API reference → interface Promise<T> interface Promise < T > interface Promise < T > Represents the completion of an asynchronous operation Grid.search(query: string, opts?: SearchOptions): SearchResult Grid. search (query: string, opts ?: SearchOptions): SearchResult Grid. search (query: string, opts ?: SearchOptions): SearchResult Find cells matching query; highlights matches, emits search, returns the result. API reference → query: string let query : string let query : string Query string retained for navigation and subsequent replacement. API reference → opts: SearchOptions | undefined let opts : SearchOptions | undefined let opts :
SearchOptions | undefined API reference → interface SearchOptions interface SearchOptions interface SearchOptions Case, whole-cell, sheet, and column constraints for grid search. API reference → interface SearchResult interface SearchResult interface SearchResult Ordered matches and active index produced by a grid search. API reference → Grid.findNext(): SearchResult Grid. findNext (): SearchResult Grid. findNext (): SearchResult Move the active match to the next match and scroll it into view. API reference → Grid.findPrev(): SearchResult Grid. findPrev (): SearchResult Grid. findPrev (): SearchResult Move the active match to the previous match and scroll it into view. API reference → Grid.clearSearch(): void Grid. clearSearch (): void Grid. clearSearch (): void Clear the current search and its highlights. API reference → Grid.replaceCurrent(replacement: string): SearchResult Grid. replaceCurrent (replacement: string): SearchResult Grid. replaceCurrent (replacement: string): SearchResult Replace 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 → Grid.replaceAll(replacement: string): ReplaceResult Grid. replaceAll (replacement: string): ReplaceResult Grid. replaceAll (replacement: string): ReplaceResult Replace 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 → interface ReplaceResult interface ReplaceResult interface ReplaceResult Replacement count and refreshed search state returned by replace-all. API reference → Grid.insertRows(at: number, count?: number): void Grid. insertRows (at: number, count ?: number): void Grid. insertRows (at: number, count ?: number): void API reference → count: number | undefined let count : number | undefined let count :
number | undefined Number of consecutive versions in the batch; at least 2. API reference → Grid.removeRows(at: number, count?: number): void Grid. removeRows (at: number, count ?: number): void Grid. removeRows (at: number, count ?: number): void API reference → Grid.insertColumns(at: number, count?: number): void Grid. insertColumns (at: number, count ?: number): void Grid. insertColumns (at: number, count ?: number): void API reference → Grid.removeColumns(at: number, count?: number): void Grid. removeColumns (at: number, count ?: number): void Grid. removeColumns (at: number, count ?: number): void API reference → Grid.highlightCells(ranges: readonly HighlightRange[] | null, color?: string): void Grid. highlightCells (ranges: readonly HighlightRange[] | null , color ?: string): void Grid. highlightCells (ranges: readonly HighlightRange[] | null , color ?: string): void Draw temporary highlights outside document history. Pass null to clear all highlights: grid.highlightCells(null). Per-range color wins over the call color. Undo does not clear highlights; use styleRange for persistent cell fills. API reference → interface HighlightRange interface HighlightRange interface HighlightRange A highlight target: a range plus an optional per-range color override. API reference → color: string | undefined let color : string | undefined let color :
string | undefined hex color, e.g. "#111111" API reference → Grid.styleRange(range: Range, style: Partial<CellStyle> | null): void Grid. styleRange (range: Range, style: Partial < CellStyle > | null ): void Grid. styleRange (range: Range, style: Partial < CellStyle > | null ): void Merge 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 → range: Range let range : Range let range : Range Inclusive table rectangle on one stable sheet ID. API reference → interface Range interface Range interface Range The Range interface represents a fragment of a document that can contain nodes and parts of text nodes. MDN Reference API reference → style: Partial<CellStyle> | null let style : Partial < CellStyle > | null let style : Partial < CellStyle > | null Optional override merged over the deterministic blue/underline link style. API reference → interface CellStyle interface CellStyle interface CellStyle Serializable formatting applied to a cell or used as a column default. API reference → Grid.setValidationRule(rule: DataValidationRule): ApplyTransactionResult Grid. setValidationRule (rule: DataValidationRule): ApplyTransactionResult Grid. setValidationRule (rule: DataValidationRule): ApplyTransactionResult interface DataValidationRule interface DataValidationRule interface DataValidationRule One stable, range-scoped data-entry rule. Blank cells are allowed unless disabled. API reference → type ApplyTransactionResult = {
status: "applied";
epoch: number;
transaction: Transaction;
warnings?: MutationIssue[];
rejections?: MutationIssue[];
} | {
status: "conflict";
expectedEpoch: number;
actualEpoch: number;
} | {
status: "rejected";
epoch: number;
issues: MutationIssue[];
} | {
status: "noop";
epoch: number;
reason: "empty" | "out-of-bounds" | "incomplete-data" | "read-only";
} type ApplyTransactionResult =
| {
status : "applied" ;
epoch : number ;
transaction : Transaction ;
warnings ?: MutationIssue [];
rejections ?: MutationIssue [];
}
| {
status : "conflict" ;
expectedEpoch : number ;
actualEpoch : number ;
}
| {
status : "rejected" ;
epoch : number ;
issues : MutationIssue [];
}
| {
status : "noop" ;
epoch : number ;
reason :
"empty" | "out-of-bounds" | "incomplete-data" | "read-only" ;
}; type ApplyTransactionResult =
| {
status : "applied" ;
epoch : number ;
transaction : Transaction ;
warnings ?: MutationIssue [];
rejections ?: MutationIssue [];
}
| {
status : "conflict" ;
expectedEpoch : number ;
actualEpoch : number ;
}
| {
status : "rejected" ;
epoch : number ;
issues : MutationIssue [];
}
| {
status : "noop" ;
epoch : number ;
reason :
| "empty"
| "out-of-bounds"
| "incomplete-data"
| "read-only" ;
}; Outcome of applying a document transaction, including conflict, rejection, and no-op states. API reference → Grid.removeValidationRule(id: string): ApplyTransactionResult Grid. removeValidationRule (id: string): ApplyTransactionResult Grid. removeValidationRule (id: string): ApplyTransactionResult Grid.setProtectedRange(range: ProtectedRange): ApplyTransactionResult Grid. setProtectedRange (range: ProtectedRange): ApplyTransactionResult Grid. setProtectedRange (range: ProtectedRange): ApplyTransactionResult range: ProtectedRange let range : ProtectedRange let range : ProtectedRange Inclusive table rectangle on one stable sheet ID. API reference → interface ProtectedRange interface ProtectedRange interface ProtectedRange Serializable client UX policy. A host resolver decides whether a local mutation may proceed. API reference → Grid.removeProtectedRange(id: string): ApplyTransactionResult Grid. removeProtectedRange (id: string): ApplyTransactionResult Grid. removeProtectedRange (id: string): ApplyTransactionResult Grid.setProtectionResolver(resolver?: ProtectionResolver, mode?: MutationPolicyMode): void Grid. setProtectionResolver (resolver ?: ProtectionResolver, mode ?: MutationPolicyMode): void Grid. setProtectionResolver (resolver ?: ProtectionResolver, mode ?: MutationPolicyMode): void Configure host-owned protected-range permissions. The resolver is synchronous so every local mutation ingress shares one atomic commit barrier. API reference → resolver: ProtectionResolver | undefined let resolver : ProtectionResolver | undefined let resolver :
ProtectionResolver | undefined API reference → type ProtectionResolver = (request: ProtectionRequest) => "allow" | "deny" type ProtectionResolver = (
request : ProtectionRequest ,
) => "allow" | "deny" ; type ProtectionResolver = (
request : ProtectionRequest ,
) => "allow" | "deny" ; Host-owned client UX permission callback for protected mutations. API reference → mode: MutationPolicyMode | undefined let mode : MutationPolicyMode | undefined let mode :
MutationPolicyMode | undefined Storage engine. Dense is the default. API reference → type MutationPolicyMode = "atomic" | "partial" type MutationPolicyMode = "atomic" | "partial" ; type MutationPolicyMode =
"atomic" | "partial" ; Atomic or partial handling for locally denied operations. API reference → Grid.setNote(addr: CellAddress, text: string | null): ApplyTransactionResult Grid. setNote (addr: CellAddress, text: string | null ): ApplyTransactionResult Grid. setNote (addr: CellAddress, text: string | null ): ApplyTransactionResult text: string | null let text : string | null let text : string | null Formula source when the cell is a formula, else the literal display text. API reference → Grid.getNote(addr: CellAddress): string | null Grid. getNote (addr: CellAddress): string | null Grid. getNote (addr: CellAddress): string | null Grid.beginEdit(row: number, col: number, initial?: string, selectAll?: boolean): void Grid. beginEdit (row: number, col: number, initial ?: string, selectAll ?: boolean): void Grid. beginEdit (row: number, col: number, initial ?: string, selectAll ?: boolean): void Open the cell editor at a view cell, optionally seeding text / selecting all. API reference → row: number let row : number let row : number 0-based row of the cell that holds the top-left corner. API reference → initial: string | undefined let initial : string | undefined let initial :
string | undefined selectAll: boolean | undefined let selectAll : boolean | undefined let selectAll :
boolean | undefined Grid.dataEdge(row: number, col: number, dRow: number, dCol: number): number | null Grid. dataEdge (row: number, col: number, dRow: number, dCol: number): number | null Grid. dataEdge (row: number, col: number, dRow: number, dCol: number): number | null Ctrl+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 → Grid.setRowHeight(row: number, height: number): void Grid. setRowHeight (row: number, height: number): void Grid. setRowHeight (row: number, height: number): void Set one row's persistent display height through document history. API reference → height: number let height : number let height : number Host height in CSS pixels for numbers or any CSS length string. API reference → Grid.setColumnWidth(col: number, width: number): void Grid. setColumnWidth (col: number, width: number): void Grid. setColumnWidth (col: number, width: number): void Set one column's width via an undoable setColumn patch. API reference → width: number let width : number let width : number Unzoomed column width in CSS pixels. API reference → Grid.autoFitRows(range?: Range): void Grid. autoFitRows (range ?: Range): void Grid. autoFitRows (range ?: Range): void Explicitly resize rows to fit wrapped content; never runs during paint. API reference → range: Range | undefined let range : Range | undefined let range :
Range | undefined Inclusive table rectangle on one stable sheet ID. API reference → Grid.autoFitColumns(cols?: readonly number[]): void Grid. autoFitColumns (cols ?: readonly number[]): void Grid. autoFitColumns (cols ?: readonly number[]): void Explicitly resize columns from a bulk worksheet read. API reference → rows: number let rows : number let rows : number Source field indices that group the output rows, outermost first. API reference → cols: number | undefined let cols : number | undefined let cols :
number | undefined visible column indices, in paint order API reference → Grid.on<E extends keyof GridEvents>(evt: E, fn: (e: GridEvents[E]) => void): () => void Grid.on< E extends keyof GridEvents >( evt : E , fn : ( e : GridEvents [ E ]) => void ) : () => void Grid.on< E extends keyof GridEvents >( evt : E , fn : ( e : GridEvents [ E ]) => void ) : () => void (type parameter) E in Grid.on<E extends keyof GridEvents>(evt: E, fn: (e: GridEvents[E]) => void): () => void (type parameter) E in Grid.on< E extends keyof GridEvents >( evt : E , fn : ( e : GridEvents [ E ]) => void ) : () => void (type parameter) E in Grid.on< E extends keyof GridEvents >( evt : E , fn : ( e : GridEvents [ E ]) => void ) : () => void interface GridEvents interface GridEvents interface GridEvents Payload map for events emitted by a Grid. API reference → evt: E extends keyof GridEvents let evt : E extends keyof GridEvents let evt : E extends keyof GridEvents API reference → Grid.refresh(): void Grid. refresh (): void Grid. refresh (): void API reference → Grid.destroy(): void Grid. destroy (): void Grid. destroy (): void Runs immediately before a retained element is removed or replaced. API reference → Grid.applyTransaction(transaction: GridTransaction): ApplyTransactionResult Grid. applyTransaction (transaction: GridTransaction): ApplyTransactionResult Grid. applyTransaction (transaction: GridTransaction): ApplyTransactionResult Apply arbitrary patches as one undoable Grid commit. No-op when read-only. Use Store.applyTransaction only for low-level writes that intentionally bypass Grid history and policy. @example import type { Grid } from "@sheetwrite/core"; function setFirstCell(grid: Grid) { return grid.applyTransaction({ patches: [ { op: "set", addr: { sheet: grid.getActiveSheet(), row: 0, col: 0 }, value: { kind: "literal", value: 42 } }, ] }); } @see Transaction API reference → transaction: GridTransaction let transaction : GridTransaction let transaction : GridTransaction Operations that actually committed after policy and bounds filtering. API reference → interface GridTransaction interface GridTransaction interface GridTransaction An undoable transaction submitted through a Grid. Grid transactions deliberately have no epoch: optimistic reconciliation is a low-level Store concern, while Grid commits are normal host-driven edits that participate in read-only policy and undo/redo history. API reference → Grid.exportSnapshot(): WorkbookSnapshot Grid. exportSnapshot (): WorkbookSnapshot Grid. exportSnapshot (): WorkbookSnapshot Deterministically export the complete authoritative workbook document. API reference → interface WorkbookSnapshot interface WorkbookSnapshot interface WorkbookSnapshot Schema-versioned serializable workbook document. API reference → Grid.applyRemoteOperations(operations: readonly DocumentOp[], options?: RemoteOperationOptions): ApplyTransactionResult Grid. applyRemoteOperations (operations: readonly DocumentOp[], options ?: RemoteOperationOptions): ApplyTransactionResult Grid. applyRemoteOperations (operations: readonly DocumentOp[], options ?: RemoteOperationOptions): ApplyTransactionResult Apply host-supplied operations without undo history or outgoing dirty state. The resulting change event has source: "remote". API reference → operations: readonly DocumentOp[] let operations : readonly DocumentOp [] let operations : readonly DocumentOp [] Canonical operations applied by the document engine. API reference → type DocumentOp = {
op: "set";
addr: CellAddress;
value: CellValue;
style?: CellStyle;
} | {
op: "setRange";
range: Range;
cells: SnapshotCell[];
} | {
op: "setBlock";
range: Range;
block: PackedCellBlock;
} | {
op: "restoreBlock";
range: Range;
encoding: "deflate-json-v1";
decodedBytes: number;
data: string;
} | {
op: "setRangeStyle";
range: Range;
style: Partial<CellStyle> | null;
} | {
op: "clearRange";
range: Range;
contents?: boolean;
style?: boolean;
} | ... 32 more ... | {
...;
} type DocumentOp = {
op : "set" ;
addr : CellAddress ;
value : CellValue ;
style ?: CellStyle ;
} | {
op : "setRange" ;
range : Range ;
cells : SnapshotCell [];
} | {
op : "setBlock" ;
range : Range ;
block : PackedCellBlock ;
} | {
op : "restoreBlock" ;
range : Range ;
encoding : "deflate-json-v1" ;
decodedBytes : number ;
data : string ;
} | {
op : "setRangeStyle" ;
range : Range ;
style : Partial < CellStyle > | null ;
} | {
op : "clearRange" ;
range : Range ;
contents ?: boolean ;
style ?: boolean ;
} | ... 32 more ... | {
... ;
} type DocumentOp = {
op : "set" ;
addr : CellAddress ;
value : CellValue ;
style ?: CellStyle ;
} | {
op : "setRange" ;
range : Range ;
cells : SnapshotCell [];
} | {
op : "setBlock" ;
range : Range ;
block : PackedCellBlock ;
} | {
op : "restoreBlock" ;
range : Range ;
encoding : "deflate-json-v1" ;
decodedBytes : number ;
data : string ;
} | {
op : "setRangeStyle" ;
range : Range ;
style : Partial < CellStyle > | null ;
} | {
op : "clearRange" ;
range : Range ;
contents ?: boolean ;
style ?: boolean ;
} | ... 32 more ... | {
... ;
} Exhaustive serializable operation union for workbook mutations. API reference → options: RemoteOperationOptions | undefined let options : RemoteOperationOptions | undefined let options :
| RemoteOperationOptions
| undefined API reference → interface RemoteOperationOptions interface RemoteOperationOptions interface RemoteOperationOptions Classification metadata for host-supplied remote operations. API reference → Grid.getCommandState(command: GridCommandName): GridCommandState Grid. getCommandState (command: GridCommandName): GridCommandState Grid. getCommandState (command: GridCommandName): GridCommandState Query undo/redo availability and formatting active/mixed/disabled state. API reference → type GridCommandName = "bold" | "italic" | "underline" | "strikethrough" | "alignLeft" | "alignCenter" | "alignRight" | "alignTop" | "alignMiddle" | "alignBottom" | "wrap" | "textColor" | "fillColor" | "border" | "clearFormat" | "merge" | "unmerge" | "sortAsc" | "sortDesc" | "exportCsv" | "exportXlsx" | "undo" | "redo" type GridCommandName =
| "bold"
| "italic"
| "underline"
| "strikethrough"
| "alignLeft"
| "alignCenter"
| "alignRight"
| "alignTop"
| "alignMiddle"
| "alignBottom"
| "wrap"
| "textColor"
| "fillColor"
| "border"
| "clearFormat"
| "merge"
| "unmerge"
| "sortAsc"
| "sortDesc"
| "exportCsv"
| "exportXlsx"
| "undo"
| "redo" ; type GridCommandName =
| "bold"
| "italic"
| "underline"
| "strikethrough"
| "alignLeft"
| "alignCenter"
| "alignRight"
| "alignTop"
| "alignMiddle"
| "alignBottom"
| "wrap"
| "textColor"
| "fillColor"
| "border"
| "clearFormat"
| "merge"
| "unmerge"
| "sortAsc"
| "sortDesc"
| "exportCsv"
| "exportXlsx"
| "undo"
| "redo" ; Built-in command names accepted by state queries and change events. API reference → interface GridCommandState interface GridCommandState interface GridCommandState Observable availability and selection-derived activity for one command. API reference → Grid.getFocusCellStyle(): CellStyle Grid. getFocusCellStyle (): CellStyle Grid. getFocusCellStyle (): CellStyle Effective style of the focus cell: its own style over its column's cellStyle. Empty when nothing is selected. API reference → Grid.getCellAtPoint(clientX: number, clientY: number): CellAddress | null Grid. getCellAtPoint (clientX: number, clientY: number): CellAddress | null Grid. getCellAtPoint (clientX: number, clientY: number): CellAddress | null Resolve browser viewport coordinates to an active-sheet cell for host-owned menus and interactions. Returns null outside the cell body. API reference → clientX: number let clientX : number let clientX : number Viewport-relative browser pointer coordinate. API reference → clientY: number let clientY : number let clientY : number Viewport-relative browser pointer coordinate. API reference → Grid.setConfig(config: GridConfig | undefined): void Grid. setConfig (config: GridConfig | undefined ): void Grid. setConfig (config: GridConfig | undefined ): void Reconfigure built-in chrome and keyboard handling without replacing the Grid or clearing selection/history. Construction-bound GridOptions are not accepted here. API reference → config: GridConfig | undefined let config : GridConfig | undefined let config :
GridConfig | undefined Built-in UI controls; providing an object enables the toolbar unless toolbar is false. API reference → interface GridConfig interface GridConfig interface GridConfig Toolbar / feature configuration. When config is set the built-in toolbar is shown; control flags default to true except the opt-in export flag. Example import type { GridConfig } from "@sheetwrite/core" ;
const config : GridConfig = {
toolbar: true ,
contextMenu: [{ action: "copy" }, { action: "paste" }],
keyboard ( event , grid ) {
if (event.altKey && event.key === "b" ) {
grid.actions. toggleBold ();
return true ;
}
return false ;
},
}; See also Grid.setConfig * See also ContextMenuItem API reference → Grid.setReadOnly(readOnly: boolean): void Grid. setReadOnly (readOnly: boolean): void Grid. setReadOnly (readOnly: boolean): void Update editability without replacing the Grid or clearing session state. API reference → readOnly: boolean let readOnly : boolean let readOnly : boolean Disables mutating interactions while preserving navigation and selection. API reference →