Listen to Spreadsheet Editor events

Requirements

These packages are required to use these features in production. Trial keys have unlimited access to all features

Web SDKPackage: Spreadsheet EditorLive demo

Spreadsheet Editor events enable your application to respond to changes and user interactions within the Spreadsheet Editor.

Events are exposed through the SpreadsheetEditorManager class and can be used to detect editor initialization, edit mode changes, sheet updates, cell modifications, selection changes, and formula bar actions. Subscribe to these events to implement custom workflows, synchronize application state, validate data, and extend the editor experience.

Editor events

Editor events provide notifications about the overall Spreadsheet Editor lifecycle and state. For example, these events occur when the editor is initialized and when the editing mode changes.

Initialize the editor

The spreadsheetEditorReady event fires when the editor has finished initializing and is ready for use. Use this when you want to perform editor operations immediately on load.

JavaScript

WebViewer(...)
  .then(instance => {
    const { documentViewer, SpreadsheetEditor } = instance.Core;
    const SpreadsheetEditorEvents = SpreadsheetEditor.SpreadsheetEditorManager.Events;
    const spreadsheetEditorManager = documentViewer.getSpreadsheetEditorManager();

    spreadsheetEditorManager.addEventListener(SpreadsheetEditorEvents.SPREADSHEET_EDITOR_READY, () => {
      spreadsheetEditorManager.setEditMode(SpreadsheetEditor.SpreadsheetEditorEditMode.EDITING);
    });
  });

spreadsheetEditorReady

Detect edit mode changes

The spreadsheetEditorEditModeChanged event fires when the editor changes modes. Use this to detect when the editor changes to view or edit mode.

JavaScript

WebViewer(...)
  .then(instance => {
    const { documentViewer, SpreadsheetEditor } = instance.Core;
    const SpreadsheetEditorEvents = SpreadsheetEditor.SpreadsheetEditorManager.Events;
    const spreadsheetEditorManager = documentViewer.getSpreadsheetEditorManager();

    spreadsheetEditorManager.addEventListener(SpreadsheetEditorEvents.EDIT_MODE_CHANGED, (mode) => {
      // console.log('Mode changed', mode);
    });
  });

spreadsheetEditorEditModeChanged

Worksheet events

Sheet events are triggered when users interact with worksheets or when sheet-level changes occur, such as switching between sheets or modifying worksheet content.

Detect active sheet updates

The activeSheetChanged event fires when the editor has switched to a different sheet.

JavaScript

WebViewer(...)
  .then(instance => {
    const { documentViewer, SpreadsheetEditor } = instance.Core;
    const SpreadsheetEditorEvents = SpreadsheetEditor.SpreadsheetEditorManager.Events;
    const spreadsheetEditorManager = documentViewer.getSpreadsheetEditorManager();

    spreadsheetEditorManager.addEventListener(SpreadsheetEditorEvents.ACTIVE_SHEET_CHANGED, (event) => {
      // console.log('Active sheet index', event.getSheetIndex());
    });
  });

activeSheetChanged

Track worksheet changes

The sheetChanged event fires when a sheet's state changes, such as renaming, deletion, creation, or visibility. The available options are listed in the SpreadsheetChangedActions definition.

JavaScript

WebViewer(...)
  .then(instance => {
    const { documentViewer, SpreadsheetEditor } = instance.Core;
    const SpreadsheetEditorEvents = SpreadsheetEditor.SpreadsheetEditorManager.Events;
    const spreadsheetEditorManager = documentViewer.getSpreadsheetEditorManager();

    spreadsheetEditorManager.addEventListener(SpreadsheetEditorEvents.SHEET_CHANGED, (event) => {
      const { SpreadsheetChangedActions}  = SpreadsheetEditor.SpreadsheetEditorManager;
      if (event.action === SpreadsheetChangedActions.CREATE_SHEET) {
        // console.log('Sheet name', event.sheetName);
        // console.log('Active sheet index', event.getActiveSheetIndex());
        // console.log('Visible sheets', event.getVisibleSheets());
      }
    });
  });

sheetChanged SpreadsheetChangedActions

Cell events

Cell events notify your application when cell data or selections change. Use these events to react to data updates, refresh dependent UI elements, or implement validation logic.

Track cell and range updates

The dataChanged event fires when a cell or cell range is modified. Changes can include values, styles, cut or paste, merge or unmerge, and add or remove rows and columns. The DataChangeType type shows all available options.

JavaScript

WebViewer(...)
  .then(instance => {
    const { documentViewer, SpreadsheetEditor } = instance.Core;
    const SpreadsheetEditorEvents = SpreadsheetEditor.SpreadsheetEditorManager.Events;
    const spreadsheetEditorManager = documentViewer.getSpreadsheetEditorManager();
    const { DataChangeType } = SpreadsheetEditor.Types;

    spreadsheetEditorManager.addEventListener(SpreadsheetEditorEvents.DATA_CHANGED, (event) => {
      // console.log('Sheet index', event.sheetIndex);
      // console.log('Cell ranges', event.cellRanges);
      // console.log('Change type', event.changeType);
      if (event.changeType === DataChangeType['DATA_CHANGE']) {
        // console.log('Data change was detected');
      }
    });
  });

dataChanged DataChangeType

Detect cell selection changes

The selectionChanged event fires when the editor selects a different cell. The editor will fire an event on initialization to indicate it has selected the top-left cell.

JavaScript

WebViewer(...)
  .then(instance => {
    const { documentViewer, SpreadsheetEditor } = instance.Core;
    const SpreadsheetEditorEvents = SpreadsheetEditor.SpreadsheetEditorManager.Events;
    const spreadsheetEditorManager = documentViewer.getSpreadsheetEditorManager();

    spreadsheetEditorManager.addEventListener(SpreadsheetEditorEvents.SELECTION_CHANGED, (event) => {
      // console.log('Cell range', event.getCellRange());
      // console.log('Bounding cells', event.getBoundingCells());
      // console.log('Selected range', event.getSelectionRangeDisplayValue());
      // console.log('Is merged', event.isMerged());
      const clipboard = event.getClipboard();
      if (clipboard.canCopy()) {
        clipboard.copy();
      }
    });
  });

selectionChanged

Formula bar events

Formula bar events notify your application when users interact with the formula bar. Use these events to monitor formula input, surface formula information, and provide search suggestions as users build formulas.

Track formula bar inputs

The formulaBarTextChangedEvent event fires when the formula bar text input changes. The following code shows how to listen to the text changed event and log each segment of the formula bar using the getInfo() function.

JavaScript

WebViewer(...)
  .then(instance => {
    const { documentViewer, SpreadsheetEditor } = instance.Core;
    const spreadsheetEditorManager = documentViewer.getSpreadsheetEditorManager();
    
    const formulaBarTextChangedHandler = (e) => {
      const segments = e.getInfo();
      for (let i=0; i<segments.length; i++) {
        console.log(`${segments[i].text} - ${segments[i].color}`);
      }
    };
    
    spreadsheetEditorManager.addEventListener(
      SpreadsheetEditor.SpreadsheetEditorManager.Events.FORMULA_BAR_TEXT_CHANGED,
      formulaBarTextChangedHandler
    );
  });

formulaBarTextChangedEvent

Access formula information

The formulaHelpEvent event fires when the selection of a formula is confirmed, like =SUM(, and returns the formula name, description, and parameter information. The following code sample shows how to listen to the help event and log the available formula information using the getFormulaInfo() function.

JavaScript

WebViewer(...)
  .then(instance => {
    const { documentViewer, SpreadsheetEditor } = instance.Core;
    const spreadsheetEditorManager = documentViewer.getSpreadsheetEditorManager();
    
    const formulaSearchEventHandler = (e) => {
      const formulaInfo = e.getFormulaInfo();
      if (formulaInfo) {
        console.log(formulaInfo.name);
        console.log(formulaInfo.description);
        console.log(formulaInfo.details);
        console.log(formulaInfo.parameters);
      }
    };
    
    spreadsheetEditorManager.addEventListener(
      SpreadsheetEditor.SpreadsheetEditorManager.Events.FORMULA_HELP,
      formulaSearchEventHandler
    );
  });

formulaHelpEvent

Detect formula searches

The formulaSearchEvent event fires when a user types in the formula bar before confirming a formula. The editor returns a list of formulas that closely match the search query. It must start with an equals sign (=) to trigger the search. The following code sample shows how to listen for the search event and log the results as an array.

JavaScript

WebViewer(...)
  .then(instance => {
    const { documentViewer, SpreadsheetEditor } = instance.Core;
    const spreadsheetEditorManager = documentViewer.getSpreadsheetEditorManager();
    
    const formulaSearchEventHandler = (e) => console.log(e.getFormulaInfoItems());
    
    spreadsheetEditorManager.addEventListener(
      SpreadsheetEditor.SpreadsheetEditorManager.Events.FORMULA_SEARCH,
      formulaSearchEventHandler
    );
  });

formulaSearchEvent