Events

The onChange callback fires whenever the user interacts with the spreadsheet — selecting cells, switching sheets, editing data, and structural changes like inserting rows or columns.

All events include a type discriminator and a timestamp (Unix milliseconds). Operation events also include sheetName.

Interactive demo

Complete example

import { useEffect, useState } from "react";
import { Model } from "@grid-is/spreadsheet-engine";
import { SpreadsheetEditor, type EditorEvent } from "@grid-is/spreadsheet-editor";
import "@grid-is/spreadsheet-editor/style.css";

export default function App() {
  const [model, setModel] = useState<Model | null>(null);

  useEffect(() => {
    async function load() {
      await Model.preconditions;
      const res = await fetch("/budget.xlsx");
      const m = await Model.fromXLSX(await res.arrayBuffer(), "budget.xlsx");
      setModel(m);
    }
    load();
  }, []);

  const handleChange = (event: EditorEvent) => {
    switch (event.type) {
      case "selection-change":
        console.log("Selected:", event.selection);
        break;
      case "sheet-change":
        console.log("Switched to:", event.sheetName);
        break;
      case "write-cell":
        console.log("Wrote:", event.cellId, "=", event.value);
        break;
      // ... handle other event types
    }
  };

  if (!model) return <p>Loading…</p>;

  return (
    <div style={{ height: "100vh" }}>
      <SpreadsheetEditor model={model} onChange={handleChange} />
    </div>
  );
}

Event types

Navigation events

Type	Key fields	Description
selection-change	selection	User moved selection to a different cell or range
sheet-change	sheetName, previousSheetName	User switched sheet tabs

Cell and data events

Type	Key fields	Description
write-cell	cellId, value	Cell value changed
clear-cells	range	Cell contents cleared
format-cells	range, format	Cell formatting changed
paste	range	Content pasted
fill	sourceRange, targetRange	Cells filled (drag to fill)

Row and column events

Type	Key fields	Description
insert-row	row, direction	Row inserted above or below
insert-column	column, direction	Column inserted left or right
delete-rows	startRow, count	Rows deleted
delete-columns	startColumn, count	Columns deleted
resize-row	row, height	Row height changed
resize-column	column, width	Column width changed

Move events

Type	Key fields	Description
move-cells	fromRange, toRange	Cells moved
move-rows	fromRange, toRange	Rows moved
move-columns	fromRange, toRange	Columns moved

Sheet management events

Type	Key fields	Description
add-sheet	sheetName	New sheet added
delete-sheet	sheetName	Sheet deleted
rename-sheet	oldName, newName	Sheet renamed

Type unions

// Navigation events only (selection + sheet switching)
type ViewerEvent = SelectionChangeEvent | SheetChangeEvent;

// All events including data operations
type EditorEvent = ViewerEvent | WriteCellEvent | PasteEvent | ClearCellsEvent | ...;