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 } from "@grid-is/editor-react";
import type { SpreadsheetController } from "@grid-is/editor-react";

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 brings it into view. With "minimal", the default, a selection that is already visible does not scroll the grid, and any other scrolls just enough to show it. A range too big for the view stays where it is as long as it fills the view. With "center" the selection is always put in the middle of the 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.

controllerRef.current?.selectCells("Z50");
controllerRef.current?.selectCells("Z50", "center");
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 />