Events and hooks

Run your code before or after specific data grid actions, using Handsontable’s API hooks (callbacks). For example, control what happens with the user’s input.

Overview

Callbacks are used to react before or after actions occur. We refer to them as hooks. Handsontable’s hooks share some characteristics with events and middleware, combining them both in a unique structure.

Events

If you only react to emitted hooks and forget about all their other features, you can treat Handsontable’s hooks as pure events. You would want to limit your scope to after prefixed hooks, so they are emitted after something has happened and the results of the actions are already committed.

hotTable.hotInstance.addHook("afterCreateRow", (row, amount) => {
  console.log(`${amount} row(s) were created, starting at index ${row}`);
});

Middleware

Middleware is a concept known in the JavaScript world from Node.js frameworks such as Express or Koa. Middleware is a callback that can pipe to a process and allow the developer to modify it. We’re no longer just reacting to an emitted event, but we can influence what’s happening inside the component and modify the process.

import { GridSettings } from "@handsontable/angular-wrapper";

gridSettings: GridSettings = {
  modifyColWidth: (width, column) => {
    if (column > 10) {
      return 150;
    }
  },
};

<hot-table [settings]="gridSettings" />

Note that the first argument is the current width that we’re going to modify. Later arguments are immutable, and additional information can be used to decide whether the data should be modified.

Handsontable hooks

We refer to all callbacks as “Handsontable hooks” because, although they share some characteristics with events and middleware, they combine them both in a unique structure. You may already be familiar with the concept as we’re not the only ones that use the hooks convention.

Almost all before-prefixed Handsontable hooks let you return false and, therefore, block the execution of an action. It may be used for validation, rejecting operation by the outside service, or blocking our native algorithm and replace it with a custom implementation.

A great example for this is our integration with HyperFormula engine where creating a new row is only possible if the engine itself will allow it:

import { GridSettings } from "@handsontable/angular-wrapper";

gridSettings: GridSettings = {
  beforeCreateRow: (row, amount) => {
    if (!hyperFormula.isItPossibleToAddRows(0, [row, amount])) {
      return false;
    }
  },
};

<hot-table [settings]="gridSettings" />

The first argument may be modified and passed on through the Handsontable hooks that are next in the queue. This characteristic is shared between before and after hooks but is more common with the former. Before something happens, we can run the data through a pipeline of hooks that may modify or reject the operation. This provides many possibilities to extend the default Handsontable functionality and customize it for your application.

Source code

TypeScript

/* file: app.component.ts */
import {Component, ViewChild, ViewEncapsulation} from '@angular/core';
import { HotTableComponent } from '@handsontable/angular-wrapper';

@Component({
  selector: 'example3-events-hooks',
  standalone: false,
  template: ` <div class="controls">
      <label>
        <input
          (change)="handleChange('fixedRowsTop', [0, 2], $event)"
          type="checkbox"
        />
        Add fixed rows
      </label>
      <br />

      <label>
        <input
          (change)="handleChange('fixedColumnsStart', [0, 2], $event)"
          type="checkbox"
        />
        Add fixed columns
      </label>
      <br />

      <label>
        <input
          (change)="handleChange('rowHeaders', [false, true], $event)"
          type="checkbox"
        />
        Enable row headers
      </label>
      <br />

      <label>
        <input
          (change)="handleChange('colHeaders', [false, true], $event)"
          type="checkbox"
        />
        Enable column headers
      </label>
      <br />
    </div>
    <div style="max-width: 440px">
      <hot-table [data]="data" [settings]="initialState"></hot-table>
    </div>`,
  encapsulation: ViewEncapsulation.None
})
export class Example3EventsHooksComponent {
  @ViewChild(HotTableComponent, { static: false }) readonly hotTable!: HotTableComponent;

  readonly data = [
    ['A1', 'B1', 'C1', 'D1', 'E1', 'F1', 'G1', 'H1', 'I1', 'J1', 'K1', 'L1'],
    ['A2', 'B2', 'C2', 'D2', 'E2', 'F2', 'G2', 'H2', 'I2', 'J2', 'K2', 'L2'],
    ['A3', 'B3', 'C3', 'D3', 'E3', 'F3', 'G3', 'H3', 'I3', 'J3', 'K3', 'L3'],
    ['A4', 'B4', 'C4', 'D4', 'E4', 'F4', 'G4', 'H4', 'I4', 'J4', 'K4', 'L4'],
    ['A5', 'B5', 'C5', 'D5', 'E5', 'F5', 'G5', 'H5', 'I5', 'J5', 'K5', 'L5'],
    ['A6', 'B6', 'C6', 'D6', 'E6', 'F6', 'G6', 'H6', 'I6', 'J6', 'K6', 'L6'],
    ['A7', 'B7', 'C7', 'D7', 'E7', 'F7', 'G7', 'H7', 'I7', 'J7', 'K7', 'L7'],
    ['A8', 'B8', 'C8', 'D8', 'E8', 'F8', 'G8', 'H8', 'I8', 'J8', 'K8', 'L8'],
    ['A9', 'B9', 'C9', 'D9', 'E9', 'F9', 'G9', 'H9', 'I9', 'J9', 'K9', 'L9'],
    [
      'A10',
      'B10',
      'C10',
      'D10',
      'E10',
      'F10',
      'G10',
      'H10',
      'I10',
      'J10',
      'K10',
      'L11',
    ],
    [
      'A11',
      'B11',
      'C11',
      'D11',
      'E11',
      'F11',
      'G11',
      'H11',
      'I11',
      'J11',
      'K11',
      'L11',
    ],
    [
      'A12',
      'B12',
      'C12',
      'D12',
      'E12',
      'F12',
      'G12',
      'H12',
      'I12',
      'J12',
      'K12',
      'L12',
    ],
  ];
  readonly initialState = {
    autoWrapRow: true,
    autoWrapCol: true,
    height: 240
  };

  handleChange(
    setting: string,
    states: number[] | boolean[],
    event: Event
  ): void {
    const target = event.target as HTMLInputElement;

    this.hotTable.hotInstance?.updateSettings({
      [setting]: states[target.checked ? 1 : 0],
    });
  }
}
/* end-file */


/* file: app.module.ts */
import { NgModule, ApplicationConfig } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { registerAllModules } from 'handsontable/registry';
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, HotTableModule } from '@handsontable/angular-wrapper';
import { CommonModule } from '@angular/common';
import { NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
/* start:skip-in-compilation */
import { Example3EventsHooksComponent } from './app.component';
/* end:skip-in-compilation */

// register Handsontable's modules
registerAllModules();

export const appConfig: ApplicationConfig = {
  providers: [
    {
      provide: HOT_GLOBAL_CONFIG,
      useValue: {
        license: NON_COMMERCIAL_LICENSE,
      } as HotGlobalConfig
    }
  ],
};

@NgModule({
  imports: [ BrowserModule, HotTableModule, CommonModule ],
  declarations: [ Example3EventsHooksComponent ],
  providers: [...appConfig.providers],
  bootstrap: [ Example3EventsHooksComponent ]
})

export class AppModule { }
/* end-file */

HTML

<div>
  <example3-events-hooks id="example3"></example3-events-hooks>
</div>

All available Handsontable hooks example

Note that some callbacks are checked on this page by default.

Tip

Open the Developer Tools Console tab to see each event details object.

Choose events to be logged:

• Select all

Source code

JavaScript

import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
import numbro from 'numbro';

// Register all Handsontable's modules.
registerAllModules();

const config = {
  data: [
    ['', 'Tesla', 'Mazda', 'Mercedes', 'Mini', 'Mitsubishi'],
    ['2017', 0, 2941, 4303, 354, 5814],
    ['2018', 3, 2905, 2867, 412, 5284],
    ['2019', 4, 2517, 4822, 552, 6127],
    ['2020', 2, 2422, 5399, 776, 4151],
  ],
  minRows: 5,
  minCols: 6,
  height: 'auto',
  stretchH: 'all',
  minSpareRows: 1,
  autoWrapRow: true,
  colHeaders: true,
  contextMenu: true,
  autoWrapCol: true,
  licenseKey: 'non-commercial-and-evaluation',
};

const example1Events = document.getElementById('example1_events');
const hooksList = document.getElementById('hooksList');
const hooks = Handsontable.hooks.getRegistered();

hooks.forEach((hook) => {
  let checked = '';

  if (
    hook === 'afterChange' ||
    hook === 'afterSelection' ||
    hook === 'afterCreateRow' ||
    hook === 'afterRemoveRow' ||
    hook === 'afterCreateCol' ||
    hook === 'afterRemoveCol'
  ) {
    checked = 'checked';
  }

  hooksList.innerHTML += `<li><label><input type="checkbox" ${checked} id="check_${hook}"> ${hook}</label></li>`;
  config[hook] = function () {
    log_events(hook, arguments);
  };
});

const start = new Date().getTime();
let i = 0;
let timer;

/**
 * @param event
 * @param data
 */
function log_events(event, data) {
  if (document.getElementById(`check_${event}`).checked) {
    const now = new Date().getTime();
    const diff = now - start;
    let str;
    const vals = [i, `@${numbro(diff / 1000).format('0.000')}`, `[${event}]`];

    for (let d = 0; d < data.length; d++) {
      try {
        str = JSON.stringify(data[d]);
      } catch (e) {
        str = data[d].toString();
      }

      if (str === void 0) {
        continue;
      }

      if (str.length > 20) {
        str = typeof data[d] === 'object' ? `object: ${str.substr(0, 20)}...}` : str.toString();
      }

      if (d < data.length - 1) {
        str += ',';
      }

      vals.push(str);
    }

    if (window.console) {
      console.log(i, `@${numbro(diff / 1000).format('0.000')}`, `[${event}]`, data);
    }

    const div = document.createElement('div');
    const text = document.createTextNode(vals.join(' '));

    div.appendChild(text);
    example1Events.appendChild(div);
    clearTimeout(timer);
    timer = setTimeout(() => {
      example1Events.scrollTop = example1Events.scrollHeight;
    }, 10);
    i++;
  }
}

const example1 = document.querySelector('#example1');

new Handsontable(example1, config);
document.querySelector('#check_select_all').addEventListener('click', function () {
  const state = this.checked;
  const inputs = document.querySelectorAll('#hooksList input[type=checkbox]');

  Array.prototype.forEach.call(inputs, (input) => {
    input.checked = state;
  });
});
document.querySelector('#hooksList input[type=checkbox]').addEventListener('click', function () {
  if (!this.checked) {
    document.getElementById('check_select_all').checked = false;
  }
});

HTML

<div class="example-container">
  <div class="example-table-container">
    <div id="example1"></div>
  </div>
  <div id="example1_events"></div>
  <aside aria-label="Tip" class="starlight-aside starlight-aside--tip">
    <p class="starlight-aside__title" aria-hidden="true">Tip</p>
    <div class="starlight-aside__content"><p>Open the Developer Tools Console tab to see each event details object.</p></div>
  </aside>
  <strong> Choose events to be logged:</strong>
  <ul id="hooksList">
    <li>
      <label><input type="checkbox" id="check_select_all" />Select all</label>
    </li>
  </ul>
</div>

Definition for source argument

It’s worth mentioning that some Handsontable hooks are triggered from the Handsontable core and some from the plugins. In some situations, it is helpful to know what triggered the callback. Did Handsontable trigger it, or was it triggered by external code or a user action? That’s why in crucial hooks, Handsontable delivers source as an argument informing you who triggered the action and providing detailed information about the source. Using the information retrieved in the source, you can create additional conditions.

source argument is optional. It takes the following values:

Value	Description
auto	Action triggered by Handsontable, and the reason for it is related directly to the settings applied to Handsontable. For example, afterCreateRow will be fired with this when minSpareRows will be greater than 0.
edit	Action triggered by Handsontable after the data has been changed, e.g., after an edit or using setData* methods.
loadData	Action triggered by Handsontable after the loadData method has been called with the data property.
updateData	Action triggered by Handsontable after the updateData method has been called; e.g., before or after a data change.
populateFromArray	Action triggered by Handsontable after requesting for populating data.
spliceCol	Action triggered by Handsontable after the column data splicing has been done.
spliceRow	Action triggered by Handsontable after the row data splicing has been done.
timeValidate	Action triggered by Handsontable after the time validator has been called, e.g., after an edit.
dateValidate	Action triggered by Handsontable after the date validator has been called, e.g., after an edit.
validateCells	Action triggered by Handsontable after the validation process has been triggered.
Autofill.fill	Action triggered by the AutoFill plugin.
ContextMenu.clearColumns	Action triggered by the ContextMenu plugin after the “Clear column” has been clicked.
ContextMenu.columnLeft	Action triggered by the ContextMenu plugin after the “Insert column left” has been clicked.
ContextMenu.columnRight	Action triggered by the ContextMenu plugin after the “Insert column right” has been clicked.
ContextMenu.removeColumn	Action triggered by the ContextMenu plugin after the “Remove column” has been clicked.
ContextMenu.removeRow	Action triggered by the ContextMenu plugin after the “Remove Row” has been clicked.
ContextMenu.rowAbove	Action triggered by the ContextMenu plugin after the “Insert row above” has been clicked.
ContextMenu.rowBelow	Action triggered by the ContextMenu plugin after the “Insert row below” has been clicked.
CopyPaste.paste	Action triggered by the CopyPaste plugin after the value has been pasted.
MergeCells	Action triggered by the MergeCells plugin when clearing the merged cells’ underlying cells.
UndoRedo.redo	Action triggered by the UndoRedo plugin after the change has been redone.
UndoRedo.undo	Action triggered by the UndoRedo plugin after the change has been undone.
ColumnSummary.set	Action triggered by the ColumnSummary plugin after the calculation has been done.
ColumnSummary.reset	Action triggered by the ColumnSummary plugin after the calculation has been reset.

List of callbacks that operate on the source parameter:

afterChange→

afterCreateCol→

afterCreateRow→

afterLoadData→

afterSetDataAtCell→

afterSetDataAtRowProp→

afterSetSourceDataAtCell→

afterRemoveCol→

afterRemoveRow→

afterValidate→

beforeChange→

beforeChangeRender→

beforeCreateCol→

beforeCreateRow→

beforeLoadData→

beforeRemoveCol→

beforeRemoveRow→

beforeValidate→

The beforeKeyDown callback

The following demo uses beforeKeyDown callback to modify some key bindings:

• Pressing Delete or Backspace on a cell deletes the cell and shifts all cells beneath it in the column up resulting in the cursor, which doesn’t move, having the value previously beneath it, now in the current cell.
• Pressing Enter in a cell where the value remains unchanged pushes all the cells in the column beneath and including the current cell down one row. This results in a blank cell under the cursor which hasn’t moved.

Source code

TypeScript

/* file: app.component.ts */
import { AfterViewInit, Component, ViewChild } from '@angular/core';
import { GridSettings, HotTableComponent } from '@handsontable/angular-wrapper';

@Component({
  selector: 'example2-events-hooks',
  standalone: false,
  template: ` <div>
    <hot-table [data]="data" [settings]="gridSettings"></hot-table>
  </div>`,
})
export class Example2EventsHooksComponent implements AfterViewInit {
  @ViewChild(HotTableComponent, { static: false }) readonly hotTable!: HotTableComponent;

  lastChange: string | any[] | null = null;

  data = [
    ['Tesla', 2017, 'black', 'black'],
    ['Nissan', 2018, 'blue', 'blue'],
    ['Chrysler', 2019, 'yellow', 'black'],
    ['Volvo', 2020, 'yellow', 'gray'],
  ];

  readonly gridSettings: GridSettings = {
    colHeaders: true,
    rowHeaders: true,
    height: 'auto',
    minSpareRows: 1,
    beforeChange: (changes: any, source: any) => {
      this.lastChange = changes;
    },
    autoWrapRow: true,
    autoWrapCol: true
  };

  ngAfterViewInit(): void {
    const hot = this.hotTable?.hotInstance;

    hot?.updateSettings({
      beforeKeyDown: (e) => {
        const selection = hot?.getSelected()?.[0];

        if (!selection) return;
        console.log(selection);

        // BACKSPACE or DELETE
        if (e.keyCode === 8 || e.keyCode === 46) {
          e.stopImmediatePropagation();
          // remove data at cell, shift up
          hot.spliceCol(selection[1], selection[0], 1);
          e.preventDefault();
        }
        // ENTER
        else if (e.keyCode === 13) {
          // if last change affected a single cell and did not change it's values
          if (
            this.lastChange &&
            this.lastChange.length === 1 &&
            this.lastChange[0][2] == this.lastChange[0][3]
          ) {
            e.stopImmediatePropagation();
            hot.spliceCol(selection[1], selection[0], 0, '');
            // add new cell
            hot.selectCell(selection[0], selection[1]);
            // select new cell
          }
        }

        this.lastChange = null;
      },
    });
  }
}
/* end-file */


/* file: app.module.ts */
import { NgModule, ApplicationConfig } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { registerAllModules } from 'handsontable/registry';
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, HotTableModule } from '@handsontable/angular-wrapper';
import { CommonModule } from '@angular/common';
import { NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
/* start:skip-in-compilation */
import { Example2EventsHooksComponent } from './app.component';
/* end:skip-in-compilation */

// register Handsontable's modules
registerAllModules();

export const appConfig: ApplicationConfig = {
  providers: [
    {
      provide: HOT_GLOBAL_CONFIG,
      useValue: {
        license: NON_COMMERCIAL_LICENSE,
      } as HotGlobalConfig
    }
  ],
};

@NgModule({
  imports: [ BrowserModule, HotTableModule, CommonModule ],
  declarations: [ Example2EventsHooksComponent ],
  providers: [...appConfig.providers],
  bootstrap: [ Example2EventsHooksComponent ]
})

export class AppModule { }
/* end-file */

HTML

<div>
  <example2-events-hooks id="example2"></example2-events-hooks>
</div>

Related API reference

Core methods

addHook()→

addHookOnce()→

hasHook()→

removeHook()→

hasHook()→

runHooks()→

Hooks

List of all Handsontable hooks→

afterListen→

afterUnlisten→