GridOptions | @sheetwrite/core

Workbook, data, rendering, policy, and built-in UI options used to create a Grid.

Package: @sheetwrite/core
Source: packages/core/src/types/grid.ts#L323

Members 18

workbook Live workbook schema adopted by the store and updated by document operations.

workbook: Workbookinterface 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 →;

data Eager column-major values loaded into workbook.activeSheet; use instead of datasource.

data?: ColumnarDatainterface 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 →;

datasource Lazy row provider requested for visible windows; use instead of eager data.

datasource?: DataSourceinterface 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.API reference →;

datasourceStorage Allocation and cache policy for datasource-backed cell storage.

datasourceStorage?: DataSourceStorageOptionsinterface 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 →;

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.

presentation?: GridPresentationtype 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 →;

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.

theme?: Partial<Themeinterface 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 →>;

readOnly Disables mutating interactions while preserving navigation and selection.

readOnly?: boolean;

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.

protectionResolver?: ProtectionResolvertype 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 →;

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.

mutationPolicy?: MutationPolicyModetype MutationPolicyMode = "atomic" | "partial";type MutationPolicyMode = "atomic" | "partial";type MutationPolicyMode =
  "atomic" | "partial";Atomic or partial handling for locally denied operations.API reference →;

transactionResourceLimits Overrides inclusive operation-count and encoded-byte ceilings for every atomic mutation.

transactionResourceLimits?: Partial<TransactionResourceLimitsinterface 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 →>;

renderers Custom cell renderers registered up front; also see Grid.defineCellRenderer.

renderers?: Record<string, CellRendererinterface 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 →>;

editors Named custom editors resolved from each column's editor field.

editors?: Record<string, CellEditorinterface 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 →>;

overscan Extra row and visible-column positions painted on each viewport edge.

overscan?: number;

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 (empty padding columns past the data, like a spreadsheet).

minColumns?: number;

config Built-in UI controls; providing an object enables the toolbar unless toolbar is false.

config?: GridConfiginterface 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;
  // … 4 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;
  // … 4 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
    >
  >;
  // … 12 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.API reference →;

Declaration

View full TypeScript declaration

export interface GridOptions {
  workbook: Workbookinterface 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 →;
  data?: ColumnarDatainterface 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 →;
  datasource?: DataSourceinterface 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.API reference →;
  datasourceStorage?: DataSourceStorageOptionsinterface 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 →;
  renderer?: "canvas" | "worker";
  workerUrl?: string | URL;
  presentation?: GridPresentationtype 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 →;
  theme?: Partial<Themeinterface 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 →>;
  readOnly?: boolean;
  hyperlinkActivation?: "event-only" | "internal-navigation" | "disabled";
  protectionResolver?: ProtectionResolvertype 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 →;
  mutationPolicy?: MutationPolicyModetype MutationPolicyMode = "atomic" | "partial";type MutationPolicyMode = "atomic" | "partial";type MutationPolicyMode =
  "atomic" | "partial";Atomic or partial handling for locally denied operations.API reference →;
  transactionResourceLimits?: Partial<TransactionResourceLimitsinterface 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 →>;
  renderers?: Record<string, CellRendererinterface 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 →>;
  editors?: Record<string, CellEditorinterface 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 →>;
  overscan?: number;
  minColumns?: number;
  config?: GridConfiginterface 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;
  // … 4 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;
  // … 4 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
    >
  >;
  // … 12 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.API reference →;
}