Controlling the editor

Attach a controllerRef to gain imperative access to the editor — useful for UI that needs to highlight cells, jump to a location, or switch sheets without user interaction.

Setup

Create a ref and pass it to the controllerRef prop:

import { useRef } from "react";
import { SpreadsheetEditor, type SpreadsheetEditorController } from "@grid-is/spreadsheet-editor";
import "@grid-is/spreadsheet-editor/style.css";

export default function App() {
  const controllerRef = useRef<SpreadsheetEditorController>(null);

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

highlightRefs

highlightRefs(refs: string[], timeInMs?: number): void

Flashes one or more cell ranges in the editor for the given duration. Useful for drawing attention to referenced cells without changing the selection.

controllerRef.current?.highlightRefs(["A1", "B2:C4"], 3000);

selectCells

selectCells(ref: string): void

Selects a cell or range and scrolls the viewport to centre it. If the reference includes a sheet prefix (e.g. "Sheet2!A1"), the editor will switch to that sheet first. If the reference cannot be parsed, the call is ignored.

controllerRef.current?.selectCells("Z50");
controllerRef.current?.selectCells("Sheet2!A1");

selectSheet

selectSheet(sheetName: string): void

Switches to the named sheet.

controllerRef.current?.selectSheet("Sheet2");

focus

focus(ref?: string): void

Moves keyboard focus to the editor’s sheet input, so the user can start navigating and typing without clicking first. Has no effect while a cell is being edited.

controllerRef.current?.focus();

Pass an optional reference to move the selection before focusing, switching sheets if the reference names one:

controllerRef.current?.focus("Sheet1!A4");

To focus the editor automatically as soon as it mounts, use the autoFocus prop instead:

<SpreadsheetEditor model={model} autoFocus />