Component Props

This page documents all props available on the SpreadsheetViewer component.

Props

model

• Type: Model
• Required: Yes

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

<SpreadsheetViewer model={model} />

The Model is typically created by loading an .xlsx file with Model.fromXLSX. See Loading Spreadsheets.

---

theme

• Type: Record<string, string>
• Required: No

An object containing CSS variable overrides for customizing the appearance of the spreadsheet.

<SpreadsheetViewer
  model={model}
  theme={{
    "--mondrian-highlight-stroke": "#3b82f6",
    "--mondrian-highlight-fill": "#dbeafe",
  }}
/>

See the Theming Guide for available theme properties and examples.

---

initialSelection

• Type: string
• Required: No

Sets the initial cell or range selection when the component mounts. Accepts an A1-style reference string, optionally prefixed with a sheet name.

// Select cell A1 on the default sheet
<SpreadsheetViewer model={model} initialSelection="A1" />

// Select a range on a specific sheet
<SpreadsheetViewer model={model} initialSelection="Sheet2!B2:E5" />

See the Initial Selection Guide for more details.

---

controllerRef

• Type: Ref<SpreadsheetViewerController>
• Required: No

A ref that receives the viewer’s imperative controller. Use it to select cells or switch sheets after the viewer has mounted.

const controllerRef = useRef<SpreadsheetViewerController>(null);

<SpreadsheetViewer model={model} controllerRef={controllerRef} />;

controllerRef.current?.selectCells("Sheet2!B2:E5");
controllerRef.current?.selectSheet("Sheet2");

See Selecting After Mount for the full behaviour of both methods.

The controller also carries overlays, which places your own DOM elements on cells. See the Cell Overlays guide.

---

onChange

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

Callback function that fires when the user interacts with the spreadsheet. Receives a ViewerEvent which can be either a selection change or sheet change event.

<SpreadsheetViewer
  model={model}
  onChange={(event) => {
    if (event.type === "selection-change") {
      console.log("Selected:", event.range);
    }
    if (event.type === "sheet-change") {
      console.log("Active sheet:", event.sheetName);
    }
  }}
/>

See the Handling Events Guide for detailed usage.

---

showErrorTooltips

• Type: boolean
• Required: No
• Default: false

When true, displays tooltips for cells containing errors (such as #DIV/0!, #REF!, etc.).

<SpreadsheetViewer model={model} showErrorTooltips />

See the Error Tooltips Guide for more information.

---

showFormulaReferencesOnCellSelection

• Type: boolean
• Required: No
• Default: false

When true, selecting a cell with a formula will highlight all referenced cells with colored dashed borders and semi-transparent fills.

<SpreadsheetViewer model={model} showFormulaReferencesOnCellSelection />

See the Formula References Guide for more information.

---

TypeScript Types

All types are exported from @grid-is/spreadsheet-viewer:

import type { SpreadsheetViewerProps, ViewerEvent, Model } from "@grid-is/spreadsheet-viewer";

For detailed event type definitions, see the Event Types Reference.