Handling Events

The SpreadsheetViewer component emits events when users interact with the spreadsheet. Use the onChange callback to listen for these events.

Interactive Demo

import { SpreadsheetViewer } from "@grid-is/mondrian-react";
import type { ViewerEvent } from "@grid-is/mondrian-react";

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

  return <SpreadsheetViewer model={model} onChange={handleChange} />;
}

Usage

Pass an onChange callback function to handle events:

import { SpreadsheetViewer } from "@grid-is/mondrian-react";
import type { ViewerEvent } from "@grid-is/mondrian-react";

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

  return <SpreadsheetViewer model={model} onChange={handleChange} />;
}

Event Types

The ViewerEvent type is a union of two event types:

Selection Change Event

Fired when the user selects a different cell or range.

if (event.type === "selection-change") {
  // event.selection - A1-style reference (e.g., "Sheet1!A1:B5")
  // event.timestamp - When the event occurred
}

Properties:

• type: "selection-change"
• selection: A1-style reference string (e.g., "Sheet1!A1:B5" or "C3")
• timestamp: Unix timestamp (milliseconds) when the event occurred

Example:

if (event.type === "selection-change") {
  console.log("User selected:", event.selection);
  // Output: "User selected: Sheet1!A1:B5"
}

Sheet Change Event

Fired when the user switches to a different sheet.

if (event.type === "sheet-change") {
  // event.sheetName - The new active sheet
  // event.previousSheetName - The sheet the user came from
  // event.timestamp - When the event occurred
}

Properties:

• type: "sheet-change"
• sheetName: The name of the newly active sheet
• previousSheetName: The name of the sheet the user switched from
• timestamp: Unix timestamp (milliseconds) when the event occurred

Example:

if (event.type === "sheet-change") {
  console.log(`Switched from "${event.previousSheetName}" to "${event.sheetName}"`);
  // Output: "Switched from "Sheet1" to "Sheet2""
}

Complete Example

Here’s a complete example showing how to track all events:

import { useState } from "react";
import { SpreadsheetViewer } from "@grid-is/mondrian-react";
import type { ViewerEvent } from "@grid-is/mondrian-react";

function App() {
  const [lastEvent, setLastEvent] = useState<ViewerEvent | null>(null);

  const handleChange = (event: ViewerEvent) => {
    setLastEvent(event);

    switch (event.type) {
      case "selection-change":
        console.log(`Selected ${event.selection} at ${event.timestamp}`);
        break;
      case "sheet-change":
        console.log(`Changed from ${event.previousSheetName} to ${event.sheetName}`);
        break;
    }
  };

  return (
    <div>
      <SpreadsheetViewer model={model} onChange={handleChange} />

      {lastEvent && (
        <div>
          Last event: {lastEvent.type} at {new Date(lastEvent.timestamp).toLocaleTimeString()}
        </div>
      )}
    </div>
  );
}

TypeScript Support

The ViewerEvent type provides full TypeScript support with discriminated unions. TypeScript will narrow the type based on the type property:

const handleChange = (event: ViewerEvent) => {
  if (event.type === "selection-change") {
    // TypeScript knows event.selection exists here
    console.log(event.selection);
  }

  if (event.type === "sheet-change") {
    // TypeScript knows event.sheetName and previousSheetName exist here
    console.log(event.sheetName, event.previousSheetName);
  }
};

Reference

For detailed type definitions, see the Event Types Reference.