@grid-is/spreadsheet-viewer

Evaluation version of GRID's React-based spreadsheet viewer.

It is one of three complementary packages for working with spreadsheets:

• @grid-is/spreadsheet-engine: the headless engine that loads workbooks, evaluates formulas, and reads and writes cells. No React required.
• @grid-is/spreadsheet-viewer (this package): a React component that renders an engine model as a read-only spreadsheet UI.
• @grid-is/spreadsheet-editor: a React component that renders an engine model as an editable spreadsheet UI.

Installation

Add our spreadsheet viewer as a project dependency with npm:

npm install @grid-is/spreadsheet-viewer

You can also use another package manager if you'd prefer:

pnpm add @grid-is/spreadsheet-viewer
# or
deno add npm:@grid-is/spreadsheet-viewer
# or
bun add @grid-is/spreadsheet-viewer
# or
yarn add @grid-is/spreadsheet-viewer

This package requires React 18 or later as a peer dependency. Your project must provide react and react-dom before you can use our spreadsheet viewer.

Using with an AI coding agent

If you are working with a coding agent (Claude Code, Cursor, Copilot, and the like), install GRID's skill so the agent gets the full, up-to-date guide for all three packages:

npx skills add GRID-is/skills

Whether or not the skill is installed, the rules below are the things that trip agents up first.

Golden rules

1. Load the model through the engine and await Model.preconditions first. Do the async loading in an effect or route loader, keep the model in state, and render the viewer only once it exists.

   import { Model } from "@grid-is/spreadsheet-engine";
   await Model.preconditions;
   const model = await Model.fromXLSX(await res.arrayBuffer(), "budget.xlsx");

2. Import the stylesheet once, at your entry point: import "@grid-is/spreadsheet-viewer/style.css";. Use that exports path, not dist/index.css directly, which bundlers such as Vite reject. Without the stylesheet the formula bar is unstyled and there are other visual bugs.

3. The container must have an explicit height. The viewer fills its parent, so a zero-height parent renders nothing visible.

4. Provide React 18 or later. react and react-dom are peer dependencies your project must supply.

5. The viewer is read-only. Change data programmatically through the engine (model.write(...)) and the viewer reflects it; there is no refresh API. If results do not appear after a programmatic formula edit, the missing step is almost always model.recalculate(ALL_FORMULA_CELLS).

6. initialSelection and selection events are A1-style refs. Single-quote sheet names that contain spaces, e.g. 'My Other Sheet'!B2:E5.

Authoritative API

The bundled type definitions are the source of truth and ship with the package. When in doubt, read or grep them rather than guessing a prop or method name. If it is not in the .d.ts, it does not exist.

grep -n "initialSelection\|ViewerEvent\|theme" node_modules/@grid-is/spreadsheet-viewer/dist/index.d.ts

Component props, events, and theme properties are also documented at https://docs.grid.is/mondrian-react/. Examples there import from @grid-is/mondrian-react; substitute @grid-is/spreadsheet-viewer.

This package also ships an AGENTS.md in its root, which points agent tools that look for that file by name back to this guide.

Getting started

The main interface in GRID's spreadsheet viewer is the SpreadsheetViewer React component. It renders a spreadsheet model in a canvas-based viewer with sheet tabs, a formula bar, and cell navigation.

The viewer works with GRID's spreadsheet engine. Use @grid-is/spreadsheet-engine to load a workbook, then pass the resulting model to SpreadsheetViewer. Remember to import the package's stylesheet once, wherever you set up your application's global styles:

import { Model } from "@grid-is/spreadsheet-engine";
import { SpreadsheetViewer } from "@grid-is/spreadsheet-viewer";
import "@grid-is/spreadsheet-viewer/style.css";

await Model.preconditions;
const res = await fetch("/budget.xlsx");
const model = await Model.fromXLSX(await res.arrayBuffer(), "budget.xlsx");

function App() {
  return (
    <div style={{ height: "600px" }}>
      <SpreadsheetViewer model={model} />
    </div>
  );
}

The container element must have an explicit height. The viewer will fill its parent container.

Handling events

Use the onChange callback to react to selection and sheet changes:

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

function App() {
  const handleChange = (event: ViewerEvent) => {
    if (event.type === "selection-change") {
      console.log("Selected:", event.selection);
    }
    if (event.type === "sheet-change") {
      console.log("Switched to sheet:", event.sheetName);
    }
  };

  return (
    <div style={{ height: "600px" }}>
      <SpreadsheetViewer model={model} onChange={handleChange} />
    </div>
  );
}

Initial selection

Set the selected cell or range when the viewer mounts with the initialSelection prop. It accepts an A1-style Excel reference, with an optional sheet name prefix:

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

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

Theming

Customise the viewer's appearance with the theme prop, which accepts CSS custom properties:

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

Resources

GRID's commercial library has further documentation on the public API.

• SpreadsheetViewer component props
• Theme properties
• Event types

When using the evaluation version of the package and following example there, just remember to replace:

import {} from /* whatever */ "@grid-is/mondrian-react";

With:

import {} from /* whatever */ "@grid-is/spreadsheet-viewer";

Conditions of use

This package is free to install and use under the following conditions. By installing it, you agree to the GRID Evaluation Licence. Permitted use:

• Internal evaluation to determine whether GRID fits your needs
• Internal prototypes and proofs of concept in non-production environments

Not permitted:

• Commercial use of any kind --- including any product, internal service, or workflow that generates revenue or cost savings, directly or indirectly
• Use in production environments
• Reverse engineering or attempting to access the source code
• Creating derivative works or modified versions
• Redistributing or sublicensing the package

If you want to get yourself set up commercially, visit https://grid.is/license.

Telemetry

While you evaluate our spreadsheet viewer, we collect anonymous telemetry to understand usage patterns. Once you license our package, all telemetry is removed.

On load, the package sends the following information to PostHog:

• Package name and version
• Environment (prod or dev)
• Runtime (Node or browser)
• If running via Node: Node version and platform
• If running in the browser: user agent, language, timezone

No spreadsheet data is shared with PostHog or any other service.