On this page
Workbook, data, rendering, policy, and built-in UI options used to create a Grid.
Examples
See also
workbookdatadatasourcedatasourceStoragerendererworkerUrlpresentationthemereadOnlyhyperlinkActivationprotectionResolvermutationPolicytransactionResourceLimitsrendererseditorsoverscanminColumnsconfig
Members 18
workbook Live workbook schema adopted by the store and updated by document operations.
data Eager column-major values loaded into workbook.activeSheet; use instead of datasource.
datasource Lazy row provider requested for visible windows; use instead of eager data.
datasourceStorage Allocation and cache policy for datasource-backed cell storage.
renderer Paint backend; defaults to main-thread canvas and falls back there if a worker fails. renderer ?: "canvas" | "worker" ;
workerUrl URL of the worker renderer module (renderer: "worker"), as served to the BROWSER — the platform Worker constructor does not consult package exports, so a bare specifier like new URL("@sheetwrite/core/worker",… workerUrl ?: string | URL ;
URL of the worker renderer module (`renderer: "worker"`), as served to the
BROWSER — the platform `Worker` constructor does not consult package
exports, so a bare specifier like `new URL("@sheetwrite/core/worker",
import.meta.url)` is NOT reliable. Either copy
`@sheetwrite/core/dist/worker.js` to your public assets and pass its URL
string (works everywhere), or use your bundler's dependency-worker import
if it has one (see `/docs/guides/worker-rendering/`). If omitted or the worker
can't be constructed, the grid falls back to the main-thread canvas
renderer and emits `renderer-fallback` once.
presentation Header presentation. Spreadsheet mode (default) paints positional A/B/C labels; data-grid mode paints each column's semantic header. Header presentation. Spreadsheet mode (default) paints positional A/B/C
labels; data-grid mode paints each column's semantic `header`. Cell
addressing, row indices, clipboard values, formulas, and exports are
unchanged in both modes.
theme Overrides merged over the default theme and host CSS custom properties.
readOnly Disables mutating interactions while preserving navigation and selection.
hyperlinkActivation Hyperlink activation never opens a browser URL. hyperlinkActivation ?: "event-only" | "internal-navigation" | "disabled" ;
Hyperlink activation never opens a browser URL. `event-only` (default)
emits a safe resolved target; `internal-navigation` additionally moves to
stable internal destinations; `disabled` rejects every activation request.
protectionResolver Host-owned client UX permission check. Host-owned client UX permission check. Servers must independently authorize
every submitted operation; this resolver is not an authentication boundary.
mutationPolicy Atomic rejects the transaction; partial skips denied operation objects.
transactionResourceLimits Overrides inclusive operation-count and encoded-byte ceilings for every atomic mutation.
renderers Custom cell renderers registered up front; also see Grid.defineCellRenderer.
editors Named custom editors resolved from each column's editor field.
overscan Extra row and visible-column positions painted on each viewport edge. Extra row and visible-column positions painted on each viewport edge.
Defaults to 6; use 0 to disable the buffer.
minColumns Render at least this many columns, adding empty columns past the data. Render at least this many columns, adding empty columns past the data. A
spreadsheet also adds empty columns to fill the host width; a data grid
adds them only through this option.
config Built-in UI controls; providing an object enables the toolbar unless toolbar is false.
Declaration
View full TypeScript declaration
export interface GridOptions {
renderer ?: "canvas" | "worker" ;
workerUrl ?: string | URL ;
hyperlinkActivation ?: "event-only" | "internal-navigation" | "disabled" ;
Referenced by
Workspace packages depending on @sheetwrite/core
@sheetwrite/benchdependency @sheetwrite/docs-startdependency @sheetwrite/reactdependency @sheetwrite/sveltedependency @sheetwrite/vuedependency @sheetwrite/xlsxdependency
Public exports naming GridOptions
interface GridOptions interface GridOptions interface GridOptions Workbook, data, rendering, policy, and built-in UI options used to create a Grid. @example import type { GridOptions } from "@sheetwrite/core"; const options: GridOptions = { workbook: { activeSheet: "sheet1", sheets: [ { id: "sheet1", name: "Sheet 1", rowCount: 1, columns: [{ key: "name", header: "Name", type: "text", width: 120 }] }, ] }, data: { rowCount: 1, columns: { name: ["Ada"] } }, config: { toolbar: true, contextMenu: true, keyboard: true }, };@see createGrid *@see GridConfigAPI reference → GridOptions.workbook: Workbook interface GridOptions { workbook : Workbook ; } interface GridOptions { workbook : Workbook ; } Live workbook schema adopted by the store and updated by document operations. API reference → Workbook.activeSheet: string interface Workbook { activeSheet : string ; } interface Workbook { activeSheet : string ; } Active sheet ID and initial tab presented when the grid is created. API reference → Workbook.sheets: Sheet[] interface Workbook { sheets : Sheet []; } interface Workbook { sheets : Sheet []; } Sheets in display/tab order. API reference → Sheet.id: string interface Sheet { id : string ; } interface Sheet { id : string ; } Stable identifier, unique within the workbook and used by every cell address. API reference → Sheet.name: string interface Sheet { name : string ; } interface Sheet { name : string ; } User-facing sheet name shown in tabs and workbook exports. API reference → Sheet.rowCount: number interface Sheet { rowCount : number ; } interface Sheet { rowCount : number ; } Row count for both in-memory and datasource-backed sheets. API reference → Sheet.columns: Column[] interface Sheet { columns : Column []; } interface Sheet { columns : Column []; } Ordered schema; array positions are the zero-based column coordinates. API reference → Column.key: string interface Column { key : string ; } interface Column { key : string ; } Non-empty key, unique within the sheet, used to map input and datasource values. API reference → Column.header: string interface Column { header : string ; } interface Column { header : string ; } Schema label used by table exports and data-grid presentation headers. API reference → Column.type: CellFormat interface Column { type : CellFormat ; } interface Column { type : CellFormat ; } Controls cell input parsing and default value formatting for this column. API reference → Column.width: number interface Column { width : number ; } interface Column { width : number ; } Unzoomed column width in CSS pixels. API reference → GridOptions.data?: ColumnarData | undefined interface GridOptions { data ?: ColumnarData | undefined ; } interface GridOptions { data ?: ColumnarData | undefined ; } Eager column-major values loaded into workbook.activeSheet; use instead of datasource. API reference → ColumnarData.rowCount: number interface ColumnarData { rowCount : number ; } interface ColumnarData { rowCount : number ; } Row count for both in-memory and datasource-backed sheets. API reference → ColumnarData.columns: Record<string, ArrayLike<CellScalar | CellValue>> interface ColumnarData { columns : Record < string , ArrayLike < CellScalar | CellValue >>; } interface ColumnarData { columns : Record < string , ArrayLike < CellScalar | CellValue > >; } Exact column runs represented by every returned row. API reference → name: string[] let name : string [] let name : string [] User-facing sheet name shown in tabs and workbook exports. API reference → GridOptions.config?: GridConfig | undefined interface GridOptions { config ?: GridConfig | undefined ; } interface GridOptions { config ?: GridConfig | undefined ; } Built-in UI controls; providing an object enables the toolbar unless toolbar is false. API reference → GridConfig.toolbar?: boolean | ToolbarItem[] | undefined interface GridConfig { toolbar ?: boolean | ToolbarItem [] | undefined ; } interface GridConfig { toolbar ?: | boolean | ToolbarItem [] | undefined ; } Show the built-in toolbar (true), hide it (false), or supply a custom item list. API reference → GridConfig.contextMenu?: boolean | ContextMenuItems | undefined interface GridConfig { contextMenu ?: boolean | ContextMenuItems | undefined ; } interface GridConfig { contextMenu ?: | boolean | ContextMenuItems | undefined ; } Built-in menu, disabled menu, static rows, or a request-aware row factory. API reference → GridConfig.keyboard?: boolean | KeyboardOptions | ((e: KeyboardEvent, grid: Grid) => boolean) | undefined interface GridConfig { keyboard ?: | boolean | KeyboardOptions | (( e : KeyboardEvent , grid : Grid ) => boolean ) | undefined ; } interface GridConfig { keyboard ?: | boolean | KeyboardOptions | (( e : KeyboardEvent , grid : Grid , ) => boolean ) | undefined ; } Built-in keyboard handling. true (default) keeps the stock Sheets-style bindings. An object replaces individual action bindings; omitted actions keep their defaults, and null disables an action's keys. For example: { bindings: { copy: { key: "c", mod: true, shift: true } } }. Menu hints and toolbar titles use these same bindings. false disables all built-in keys. A function intercepts each keydown before the defaults; return true to consume it, false to let the built-in handler continue. API reference → interface Workbook {
sheets: Sheet[];
activeSheet: SheetId;
namedRanges?: NamedRangeSnapshot[];
} interface Workbook { sheets : Sheet []; activeSheet : SheetId ; namedRanges ?: NamedRangeSnapshot []; } interface Workbook { sheets : Sheet []; activeSheet : SheetId ; namedRanges ?: NamedRangeSnapshot []; } Live workbook schema containing ordered sheets and the active sheet ID. API reference → interface ColumnarData {
rowCount: number;
columns: Record<string, ArrayLike<CellScalar | CellValue>>;
} interface ColumnarData { rowCount : number ; columns : Record < string , ArrayLike < CellScalar | CellValue >>; } interface ColumnarData { rowCount : number ; columns : Record < string , ArrayLike < CellScalar | CellValue > >; } Eager column-oriented values used to initialize a sheet. API reference → interface DataSource {
readonly capabilities: DataSourceCapabilities;
getRows(request: DataSourceRequest): Promise<DataSourcePage>;
} interface DataSource { readonly capabilities : DataSourceCapabilities ; getRows ( request : DataSourceRequest ) : Promise < DataSourcePage >; } interface DataSource { readonly capabilities : DataSourceCapabilities ; getRows ( request : DataSourceRequest , ) : Promise < DataSourcePage >; } Host callback that asynchronously loads cancellable rectangular pages. @example import type { DataSource, RowData } from "@sheetwrite/core"; const rows: RowData[] = [{ amount: 12 }, { amount: 18 }]; const datasource: DataSource = { capabilities: { protocol: 2, columns: "windowed" }, async getRows(request) { request.signal.throwIfAborted(); return { protocol: 2, start: request.start, columns: request.columns, rows: rows.slice(request.start, request.end).map((row) => Object.fromEntries(request.columns.flatMap((band) => band.keys.map((key) => [key, row[key] ?? null])))), }; }, }; @see GridOptions.datasource @see DataSourceRequest API reference → interface DataSourceStorageOptions {
mode?: "dense" | "paged";
chunkRows?: number;
cacheBytes?: number;
dirtyCellLimit?: number;
} interface DataSourceStorageOptions { mode ?: "dense" | "paged" ; chunkRows ?: number ; cacheBytes ?: number ; dirtyCellLimit ?: number ; } interface DataSourceStorageOptions { mode ?: "dense" | "paged" ; chunkRows ?: number ; cacheBytes ?: number ; dirtyCellLimit ?: number ; } Dense or allocation-lazy paged storage policy for datasource cells. API reference → type GridPresentation = "spreadsheet" | "data-grid"; type GridPresentation = "spreadsheet" | "data-grid" ; type GridPresentation = "spreadsheet" | "data-grid" ; Header semantics used by the retained canvas and accessibility mirror. API reference → interface Theme {
font: string;
bg: string;
fg: string;
gridLine: string;
headerBg: string;
headerFg: string;
selection: string;
selectionBorder: string;
rowHeight: number;
headerHeight: number;
rowHeaderWidth: number;
searchMatch: string;
searchActiveMatch: string;
highlight: string;
} interface Theme { font : string ; bg : string ; fg : string ; gridLine : string ; headerBg : string ; headerFg : string ; selection : string ; selectionBorder : string ; rowHeight : number ; headerHeight : number ; rowHeaderWidth : number ; searchMatch : string ; searchActiveMatch : string ; highlight : string ; } interface Theme { font : string ; bg : string ; fg : string ; gridLine : string ; headerBg : string ; headerFg : string ; selection : string ; selectionBorder : string ; rowHeight : number ; headerHeight : number ; rowHeaderWidth : number ; searchMatch : string ; searchActiveMatch : string ; highlight : string ; } Resolved canvas colors, typography, and geometry used for painting. API reference → type ProtectionResolver = (
request: ProtectionRequest,
) => "allow" | "deny"; type ProtectionResolver = ( request : ProtectionRequest , ) => "allow" | "deny" ; type ProtectionResolver = ( request : ProtectionRequest , ) => "allow" | "deny" ; Host-owned client UX permission callback for protected mutations. API reference → type MutationPolicyMode = "atomic" | "partial"; type MutationPolicyMode = "atomic" | "partial" ; type MutationPolicyMode = "atomic" | "partial" ; Atomic or partial handling for locally denied operations. API reference → interface TransactionResourceLimits {
maxOperations: number;
maxEncodedBytes: number;
} interface TransactionResourceLimits { maxOperations : number ; maxEncodedBytes : number ; } interface TransactionResourceLimits { maxOperations : number ; maxEncodedBytes : number ; } Public ceilings shared by transaction producers, persistence, transport, and replay. Limits measure the submitted operation array itself, not the logical cell area covered by compact operations. API reference → interface CellRenderer {
canvas?(ctx: CanvasRenderingContext2D, c: CellPaintContext): void;
dom?(c: CellPaintContext): HTMLElement;
update?(element: HTMLElement, c: CellPaintContext): void;
destroy?(element: HTMLElement): void;
} interface CellRenderer { canvas ? ( ctx : CanvasRenderingContext2D , c : CellPaintContext ) : void ; dom ? ( c : CellPaintContext ) : HTMLElement ; update ? ( element : HTMLElement , c : CellPaintContext ) : void ; destroy ? ( element : HTMLElement ) : void ; } interface CellRenderer { canvas ? ( ctx : CanvasRenderingContext2D , c : CellPaintContext , ) : void ; dom ? ( c : CellPaintContext , ) : HTMLElement ; update ? ( element : HTMLElement , c : CellPaintContext , ) : void ; destroy ? ( element : HTMLElement , ) : void ; } Custom cell renderer hooks for the main-thread canvas or retained DOM overlay. API reference → interface CellEditor {
mount(
host: HTMLElement,
context: CellEditorContext,
): CellEditorInstance;
} interface CellEditor { mount ( host : HTMLElement , context : CellEditorContext , ) : CellEditorInstance ; } interface CellEditor { mount ( host : HTMLElement , context : CellEditorContext , ) : CellEditorInstance ; } Framework-neutral named editor definition registered through GridOptions.editors. API reference → interface GridConfig {
toolbar?: boolean | ToolbarItem[];
bold?: boolean;
italic?: boolean;
align?: boolean;
textColor?: boolean;
fillColor?: boolean;
border?: boolean;
clearFormat?: boolean;
merge?: boolean;
sort?: boolean;
export?: boolean;
icons?: Partial<Record<ToolbarActionName, ToolbarIcon>>;
contextMenu?: boolean | ContextMenuItems;
undo?: boolean;
// … 7 more lines — see the API reference
} interface GridConfig { toolbar ?: boolean | ToolbarItem []; bold ?: boolean ; italic ?: boolean ; align ?: boolean ; textColor ?: boolean ; fillColor ?: boolean ; border ?: boolean ; clearFormat ?: boolean ; merge ?: boolean ; sort ?: boolean ; export ?: boolean ; icons ?: Partial < Record < ToolbarActionName , ToolbarIcon >>; contextMenu ?: boolean | ContextMenuItems ; undo ?: boolean ; // … 7 more lines — see the API reference } interface GridConfig { toolbar ?: boolean | ToolbarItem []; bold ?: boolean ; italic ?: boolean ; align ?: boolean ; textColor ?: boolean ; fillColor ?: boolean ; border ?: boolean ; clearFormat ?: boolean ; merge ?: boolean ; sort ?: boolean ; export ?: boolean ; icons ?: Partial < Record < ToolbarActionName , ToolbarIcon > >; // … 13 more lines — see the API reference } Toolbar / feature configuration. When config is set the built-in toolbar is shown; control flags default to true except the opt-in export flag. @example import type { GridConfig } from "@sheetwrite/core"; const config: GridConfig = { toolbar: true, contextMenu: [{ action: "copy" }, { action: "paste" }], keyboard(event, grid) { if (event.altKey && event.key === "b") { grid.actions.toggleBold(); return true; } return false; }, }; @see Grid.setConfig @see ContextMenuItem API reference →