Initial Selection

You can set an initial cell or range selection when the SpreadsheetViewer mounts using the initialSelection prop.

Interactive Demo

Usage

The initialSelection prop accepts an A1-style reference string, optionally prefixed with a sheet name.

Programmatic References

You can build a reference programmatically using the re-exported A1Ref class:

import { SpreadsheetViewer, A1Ref } from "@grid-is/mondrian-react";

const ref = new A1Ref(selection, { sheetName: "Summary" });
<SpreadsheetViewer model={model} initialSelection={ref.toString()} />;

A1-Style Reference Format

The A1-style reference format follows Excel’s standard notation:

A1 - Single cell
A1:B5 - Range of cells
Sheet1!A1 - Cell on a specific sheet
Sheet1!A1:B5 - Range on a specific sheet

Selecting After Mount

initialSelection is only read when the viewer mounts. To change the selection later, attach a controllerRef:

import { useRef } from "react";
import { SpreadsheetViewer, type SpreadsheetViewerController } from "@grid-is/mondrian-react";

function App() {
  const controllerRef = useRef<SpreadsheetViewerController>(null);

  return (
    <>
      <button onClick={() => controllerRef.current?.selectCells("Summary!B5")}>Go to Summary</button>
      <SpreadsheetViewer model={model} controllerRef={controllerRef} />
    </>
  );
}

selectCells

selectCells(ref: string): void

Selects a cell or range and scrolls the viewport to centre it — the same result as initialSelection, at any time. With a sheet prefix (e.g. "Summary!B5") the viewer switches to that sheet first.

Without a sheet prefix the selection applies to the current sheet. This differs from initialSelection, which applies to the first sheet in the workbook.

The call is ignored if the reference cannot be parsed, names a sheet the workbook does not have, or falls outside the sheet. A reference that names another sheet still switches to that sheet, even when its range falls outside it.

selectSheet

selectSheet(sheetName: string): void

Switches to the named sheet, the same as clicking its tab. Unknown sheet names are ignored.

Events

Both methods emit the same onChange events as the equivalent user action, so a host can keep its own state in sync. selectCells emits selection-change, and also sheet-change when it switches sheets.

Handling Events - Listen to selection changes
Component Props - See all available props