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 SpreadsheetController } from "@grid-is/spreadsheet-editor";
import "@grid-is/spreadsheet-editor/style.css";

export default function App() {
  const controllerRef = useRef<SpreadsheetController>(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, reveal?: "minimal" | "center"): void

Selects a cell or range and scrolls it into view. 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.

The optional reveal argument sets the scrolling: "minimal" (the default) scrolls only as far as needed to bring the selection into view, and "center" centres the selection in the viewport.

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 />

overlays

overlays: SpreadsheetOverlays;

Places your own DOM on top of cells, such as an agent’s cursor or a suggested edit with an accept button. See the Cell overlays guide.

const id = controllerRef.current?.overlays.add({ target: "B2", element });