@grid-is/spreadsheet-editor

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

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: a React component that renders an engine model as a read-only spreadsheet UI.
• @grid-is/spreadsheet-editor (this package): a React component that renders an engine model as an editable spreadsheet UI.

Installation

Add our spreadsheet editor as a project dependency with npm:

npm install @grid-is/spreadsheet-editor

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

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

This package has three peer dependencies that your project must provide: react and react-dom (version 18 or later), and @grid-is/spreadsheet-engine, which the editor uses to load and recalculate workbooks.

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 editor 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. Provide all three peer dependencies. Unlike the engine and viewer, the editor's bundle is not self-contained: your project must supply react and react-dom (version 18 or later) and @grid-is/spreadsheet-engine.

3. Import the stylesheet once, at your entry point: import "@grid-is/spreadsheet-editor/style.css";. Use that exports path, not dist/index.css directly, which bundlers such as Vite reject.

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

5. onChange events are after-the-fact notifications: by the time they fire the editor has already applied the change to the live model, so do not re-apply them. User edits are immediately readable through the engine (model.readValue(...)). Use events for autosave, dirty-state, or audit logs.

6. Formulas typed by users recalculate on their own. A programmatic formula edit (wb.editCell(...)) still needs model.recalculate(ALL_FORMULA_CELLS) for results to appear. Note there is no theme prop (unlike the viewer); sheet refs are A1-style, single-quoted when the sheet name has spaces.

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 "EditorEvent\|SpreadsheetSize\|fontConfig\|controllerRef" node_modules/@grid-is/spreadsheet-editor/dist/index.d.ts

The component is also documented at https://docs.grid.is/editor/. Examples there import from @grid-is/editor-react and @grid-is/apiary; substitute @grid-is/spreadsheet-editor and @grid-is/spreadsheet-engine respectively.

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 editor is the SpreadsheetEditor React component. It renders an editable spreadsheet with a formula bar, cell navigation, and full keyboard support.

The editor works with GRID's spreadsheet engine. Use @grid-is/spreadsheet-engine to load a workbook, then pass the resulting model to SpreadsheetEditor. 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 { SpreadsheetEditor } from "@grid-is/spreadsheet-editor";
import "@grid-is/spreadsheet-editor/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" }}>
      <SpreadsheetEditor model={model} />
    </div>
  );
}

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

Handling events

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

function App() {
  return (
    <div style={{ height: "600px" }}>
      <SpreadsheetEditor
        model={model}
        onChange={(event) => {
          console.log("Editor event:", event);
        }}
      />
    </div>
  );
}

Initial selection

Set the selected cell or range when the editor 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
<SpreadsheetEditor model={model} initialSelection="A1" />

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

Resources

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

• SpreadsheetEditor documentation

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

import { SpreadsheetEditor } from "@grid-is/editor-react";

With:

import { SpreadsheetEditor } from "@grid-is/spreadsheet-editor";

And likewise replace any imports from @grid-is/apiary with @grid-is/spreadsheet-engine.

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 editor, 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.