Component Props

This page documents all props available on the SpreadsheetEditor component.

Props

model

• Type: Model
• Required: Yes

The Apiary model instance to render. This object contains all the data, formulas, and formatting for the spreadsheet.

<SpreadsheetEditor model={model} />

See the Loading Spreadsheets guide for how to create a Model from an .xlsx file.

---

onChange

• Type: (event: EditorEvent) => void
• Required: No

Callback that fires whenever the user interacts with the spreadsheet — selecting cells, switching sheets, editing data, and structural changes.

import type { EditorEvent } from "@grid-is/editor-react";

<SpreadsheetEditor
  model={model}
  onChange={(event) => {
    console.log(event.type, event);
  }}
/>

See the Events guide for all event types.

---

initialSelection

• Type: string
• Required: No

Sets the initial cell selection in A1 notation. The editor will also scroll to make the selection visible. Only applied on first render.

<SpreadsheetEditor model={model} initialSelection="B5" />

---

size

• Type: SpreadsheetSize
• Required: No

Constrains the maximum number of rows and columns the user can navigate to.

<SpreadsheetEditor model={model} size={{ maxRows: 100, maxCols: 26 }} />

SpreadsheetSize

interface SpreadsheetSize {
  maxRows?: number; // 0-based index of the last navigable row
  maxCols?: number; // 0-based index of the last navigable column
}

---

fontConfig

• Type: FontConfig
• Required: No

Tells the editor where to load spreadsheet fonts from. Fonts are only loaded when baseUrl is set.

The package ships no font files. Host them yourself (they are published in @grid-is/fontstack) and point baseUrl at the directories:

<SpreadsheetEditor
  fontConfig={{ baseUrl: { open: "/fonts/open/", restricted: "/fonts/restricted/" } }}
  model={model}
/>

Use fontFilter to narrow what gets loaded, either by licence or by font id.

<SpreadsheetEditor fontConfig={{ baseUrl, fontFilter: "open" }} model={model} />

---

showFormulaReferencesOnCellSelection

• Type: boolean
• Required: No

When true, selecting a cell that contains a formula will highlight all cells it references.

<SpreadsheetEditor model={model} showFormulaReferencesOnCellSelection />

See the Formula Reference Highlighting guide for details.

---

autoFocus

• Type: boolean
• Required: No

When true, the editor takes keyboard focus as soon as it mounts, so the user can navigate and type without clicking first. Only applied on first render.

<SpreadsheetEditor model={model} autoFocus />

To focus the editor later on demand, use the controller’s focus() method.

---

controllerRef

• Type: Ref<SpreadsheetController>
• Required: No

A React ref that exposes imperative methods on the editor.

import { useRef } from "react";
import type { SpreadsheetController } from "@grid-is/editor-react";

const controllerRef = useRef<SpreadsheetController>(null);

<SpreadsheetEditor model={model} controllerRef={controllerRef} />

See the Controlling the Editor guide for usage examples.

SpreadsheetController

interface SpreadsheetController {
  focus: (ref?: string) => void;
  highlightRefs: (refs: string[], timeInMs?: number) => void;
  selectCells: (ref: string, reveal?: "minimal" | "center") => void;
  selectSheet: (sheetName: string) => void;
}

---

TypeScript Types

All types are exported from @grid-is/editor-react:

import type {
  EditorEvent,
  ViewerEvent,
  SelectionChangeEvent,
  SheetChangeEvent,
  OnChange,
  SpreadsheetSize,
  SpreadsheetController,
} from "@grid-is/editor-react";