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.

If your logic grows beyond a single hook and needs shared state or a lifecycle, package it as a custom plugin instead.

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.

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

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.

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

3
gridSettings: GridSettings = {
4
  modifyColWidth: (width, column) => {
5
    if (column > 10) {
6
      return 150;
7
    }
8
  },
9
};

1
<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.

For content-aware maximum width capping, see the Column widths guide.

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:

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

3
gridSettings: GridSettings = {
4
  beforeCreateRow: (row, amount) => {
5
    if (!hyperFormula.isItPossibleToAddRows(0, [row, amount])) {
6
      return false;
7
    }
8
  },
9
};

1
<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.

Commonly used hooks

Handsontable exposes hundreds of hooks. The ones below are the hooks you reach for most often, grouped by what they do. Unlike the source argument list further down this page, this grouping is about purpose, not about which callbacks receive a source argument.

Lifecycle — run code as the grid instance starts up.

beforeInit

afterInit

Data changes — react to or alter the user’s edits. Returning false from beforeChange rejects the change.

beforeChange

afterChange

When columns[].data is a function, the prop field in each change tuple is that accessor function. Use propToCol() to resolve the visual column index. See Binding to data: Identify changed columns in hooks.

Row and column structure (CRUD) — track rows and columns being added or removed. Each before variant can return false to block the operation.

Selection — respond to the user selecting cells.

afterSelection

afterSelectionEnd

Mouse interaction — respond to mouse actions on cells.

Keyboard interaction — respond to or override key presses. See the beforeKeyDown section below for a demo.

beforeKeyDown

afterDocumentKeyDown

How validation affects hook order

When an edited cell has a validator, Handsontable runs the validation asynchronously. This applies to every validator, including one that calls its callback synchronously. It also applies to the built-in validators that cell types such as numeric, date, time, dropdown, and autocomplete use, so a cell can run a validator even without a custom validator function. The grid commits the change and fires the change-related hooks only after the validators for all edited cells resolve. As a result, the order in which hooks fire during an edit depends on whether the edited cell runs a validator.

When the edited cell runs no validator, the hooks fire synchronously:

When the edited cell runs a validator, the grid defers the change until validation finishes, so afterSelection fires before the change is committed:

The exact sequence depends on how you confirm the edit. The lists above describe confirming an edit with Enter or Tab, which moves the selection and fires afterSelection while validation is still pending.

To act on a committed, validated value, use the afterChange or afterValidate hook. Don’t rely on a hook firing before or after afterSelection, because a validator changes that order. The beforeValidate and afterValidate hooks fire only when a validator is defined.

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

5
@Component({
6
  selector: 'example3-events-hooks',
7
  standalone: true,
8
  imports: [HotTableModule],
9
  template: ` <div class="example-controls-container">
10
      <div class="controls">
11
        <label>
12
          <input
13
            (change)="handleChange('fixedRowsTop', [0, 2], $event)"
14
            type="checkbox"
15
          />
16
          Add fixed rows
17
        </label>
18
        <br />
19

20
        <label>
21
          <input
22
            (change)="handleChange('fixedColumnsStart', [0, 2], $event)"
23
            type="checkbox"
24
          />
25
          Add fixed columns
26
        </label>
27
        <br />
28

29
        <label>
30
          <input
31
            (change)="handleChange('rowHeaders', [false, true], $event)"
32
            type="checkbox"
33
          />
34
          Enable row headers
35
        </label>
36
        <br />
37

38
        <label>
39
          <input
40
            (change)="handleChange('colHeaders', [false, true], $event)"
41
            type="checkbox"
42
          />
43
          Enable column headers
44
        </label>
45
        <br />
46
      </div>
47
    </div>
48
    <div style="max-width: 440px">
49
      <hot-table [data]="data" [settings]="initialState"></hot-table>
50
    </div>`,
51
  encapsulation: ViewEncapsulation.None
52
})
53
export class AppComponent {
54
  @ViewChild(HotTableComponent, { static: false }) readonly hotTable!: HotTableComponent;
55

56
  readonly data = [
57
    ['A1', 'B1', 'C1', 'D1', 'E1', 'F1', 'G1', 'H1', 'I1', 'J1', 'K1', 'L1'],
58
    ['A2', 'B2', 'C2', 'D2', 'E2', 'F2', 'G2', 'H2', 'I2', 'J2', 'K2', 'L2'],
59
    ['A3', 'B3', 'C3', 'D3', 'E3', 'F3', 'G3', 'H3', 'I3', 'J3', 'K3', 'L3'],
60
    ['A4', 'B4', 'C4', 'D4', 'E4', 'F4', 'G4', 'H4', 'I4', 'J4', 'K4', 'L4'],
61
    ['A5', 'B5', 'C5', 'D5', 'E5', 'F5', 'G5', 'H5', 'I5', 'J5', 'K5', 'L5'],
62
    ['A6', 'B6', 'C6', 'D6', 'E6', 'F6', 'G6', 'H6', 'I6', 'J6', 'K6', 'L6'],
63
    ['A7', 'B7', 'C7', 'D7', 'E7', 'F7', 'G7', 'H7', 'I7', 'J7', 'K7', 'L7'],
64
    ['A8', 'B8', 'C8', 'D8', 'E8', 'F8', 'G8', 'H8', 'I8', 'J8', 'K8', 'L8'],
65
    ['A9', 'B9', 'C9', 'D9', 'E9', 'F9', 'G9', 'H9', 'I9', 'J9', 'K9', 'L9'],
66
    [
67
      'A10',
68
      'B10',
69
      'C10',
70
      'D10',
71
      'E10',
72
      'F10',
73
      'G10',
74
      'H10',
75
      'I10',
76
      'J10',
77
      'K10',
78
      'L11',
79
    ],
80
    [
81
      'A11',
82
      'B11',
83
      'C11',
84
      'D11',
85
      'E11',
86
      'F11',
87
      'G11',
88
      'H11',
89
      'I11',
90
      'J11',
91
      'K11',
92
      'L11',
93
    ],
94
    [
95
      'A12',
96
      'B12',
97
      'C12',
98
      'D12',
99
      'E12',
100
      'F12',
101
      'G12',
102
      'H12',
103
      'I12',
104
      'J12',
105
      'K12',
106
      'L12',
107
    ],
108
  ];
109
  readonly initialState = {
110
    autoWrapRow: true,
111
    autoWrapCol: true,
112
    height: 240
113
  };
114

115
  handleChange(
116
    setting: string,
117
    states: number[] | boolean[],
118
    event: Event
119
  ): void {
120
    const target = event.target as HTMLInputElement;
121

122
    this.hotTable.hotInstance?.updateSettings({
123
      [setting]: states[target.checked ? 1 : 0],
124
    });
125
  }
126
}
127
/* end-file */
128

129

130

131
/* file: app.config.ts */
132
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
133
import { registerAllModules } from 'handsontable/registry';
134
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
135

136
// register Handsontable's modules
137
registerAllModules();
138

139
export const appConfig: ApplicationConfig = {
140
  providers: [
141
    provideZoneChangeDetection({ eventCoalescing: true }),
142
    {
143
      provide: HOT_GLOBAL_CONFIG,
144
      useValue: { license: NON_COMMERCIAL_LICENSE } as HotGlobalConfig,
145
    },
146
  ],
147
};
148
/* end-file */

1
<div>
2
  <example3-events-hooks id="example3"></example3-events-hooks>
3
</div>

All available Handsontable hooks example

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

Choose events to be logged:

Select all

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
// Register all Handsontable's modules.
4
registerAllModules();
5
const config = {
6
    data: [
7
        ['', 'Tesla', 'Mazda', 'Mercedes', 'Mini', 'Mitsubishi'],
8
        ['2017', 0, 2941, 4303, 354, 5814],
9
        ['2018', 3, 2905, 2867, 412, 5284],
10
        ['2019', 4, 2517, 4822, 552, 6127],
11
        ['2020', 2, 2422, 5399, 776, 4151],
12
    ],
13
    minRows: 5,
14
    minCols: 6,
15
    height: 'auto',
16
    stretchH: 'all',
17
    minSpareRows: 1,
18
    autoWrapRow: true,
19
    colHeaders: true,
20
    contextMenu: true,
21
    autoWrapCol: true,
22
    dropdownMenu: true,
23
    filters: true,
24
    columnSorting: true,
25
    mergeCells: true,
26
    comments: true,
27
    manualColumnMove: true,
28
    manualRowMove: true,
29
    licenseKey: 'non-commercial-and-evaluation',
30
};
31
const example1Events = document.getElementById('example1_events');
32
const hooksList = document.getElementById('hooksList');
33
const hooks = Handsontable.hooks.getRegistered();
34
hooks.forEach((hook) => {
35
    let checked = '';
36
    if (hook === 'afterChange' ||
37
        hook === 'afterSelection' ||
38
        hook === 'afterCreateRow' ||
39
        hook === 'afterRemoveRow' ||
40
        hook === 'afterCreateCol' ||
41
        hook === 'afterRemoveCol') {
42
        checked = 'checked';
43
    }
44
    hooksList.innerHTML += `<li><label><input type="checkbox" ${checked} id="check_${hook}"> ${hook}</label></li>`;
45
    config[hook] = function () {
46
        log_events(hook, arguments);
47
    };
48
});
49
const start = new Date().getTime();
50
let i = 0;
51
let timer;
52
/**
53
 * @param event
54
 * @param data
55
 */
56
function log_events(event, data) {
57
    if (document.getElementById(`check_${event}`).checked) {
58
        const now = new Date().getTime();
59
        const diff = now - start;
60
        let str;
61
        const vals = [i, `@${(diff / 1000).toFixed(3)}`, `[${event}]`];
62
        for (let d = 0; d < data.length; d++) {
63
            try {
64
                str = JSON.stringify(data[d]);
65
            }
66
            catch (e) {
67
                str = data[d].toString();
68
            }
69
            if (str === void 0) {
70
                continue;
71
            }
72
            if (str.length > 20) {
73
                str = typeof data[d] === 'object' ? `object: ${str.substr(0, 20)}...}` : str.toString();
74
            }
75
            if (d < data.length - 1) {
76
                str += ',';
77
            }
78
            vals.push(str);
79
        }
80
        if (window.console) {
81
            console.log(i, `@${(diff / 1000).toFixed(3)}`, `[${event}]`, data);
82
        }
83
        const div = document.createElement('div');
84
        const text = document.createTextNode(vals.join(' '));
85
        div.appendChild(text);
86
        example1Events.appendChild(div);
87
        clearTimeout(timer);
88
        timer = setTimeout(() => {
89
            example1Events.scrollTop = example1Events.scrollHeight;
90
        }, 10);
91
        i++;
92
    }
93
}
94
const example1 = document.querySelector('#example1');
95
new Handsontable(example1, config);
96
document.querySelector('#check_select_all').addEventListener('click', function () {
97
    const state = this.checked;
98
    const inputs = document.querySelectorAll('#hooksList input[type=checkbox]');
99
    Array.prototype.forEach.call(inputs, (input) => {
100
        input.checked = state;
101
    });
102
});
103
document.querySelector('#hooksList input[type=checkbox]').addEventListener('click', function () {
104
    if (!this.checked) {
105
        document.getElementById('check_select_all').checked = false;
106
    }
107
});

1
<div class="example-container">
2
  <div class="example-table-container">
3
    <div id="example1"></div>
4
  </div>
5
  <div id="example1_events"></div>
6
  <aside aria-label="Tip" class="starlight-aside starlight-aside--tip">
7
    <p class="starlight-aside__title" aria-hidden="true">Tip</p>
8
    <div class="starlight-aside__content"><p>Open the Developer Tools Console tab to see each event details object.</p></div>
9
  </aside>
10
  <strong> Choose events to be logged:</strong>
11
  <ul id="hooksList">
12
    <li>
13
      <label><input type="checkbox" id="check_select_all" />Select all</label>
14
    </li>
15
  </ul>
16
</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 `setDataAtCell()`, `setDataAtRowProp()`, or `setSourceDataAtCell()` 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.
`updateSettings`	Action triggered by `updateSettings()` when its settings object includes the `data` option. The `beforeUpdateData` and `afterUpdateData` hooks receive this source.
`populateFromArray`	Action triggered by Handsontable after the `populateFromArray()` method has been called.
`spliceCol`	Action triggered by Handsontable after the `spliceCol()` method has been called.
`spliceRow`	Action triggered by Handsontable after the `spliceRow()` method has been called.
`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 `validateCells()` method has been called.
`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.

Prevent feedback loops

After initialization, updateSettings() uses updateData() internally when its settings object includes data. The beforeUpdateData and afterUpdateData hooks receive source === 'updateSettings'. The resulting afterChange hook receives changes === null and source === 'updateData'.

Calling updateSettings({ data }) inside afterChange triggers afterChange again. Check the source before replacing data to prevent a feedback loop. In this callback snippet, nextData contains the dataset supplied by your application:

1
hot.addHook('afterChange', (changes, source) => {
2
  if (source === 'updateData') {
3
    return;
4
  }
5

6
  hot.updateSettings({
7
    data: nextData,
8
  });
9
});

The beforeChange hook doesn’t run for whole-dataset replacements. Use beforeUpdateData to intercept data passed through updateSettings({ data }).

The same risk applies to a direct, single-cell write with setDataAtCell(): without a custom source, the write arrives in afterChange with source === 'edit' (see the source table above), indistinguishable from a user edit, so calling setDataAtCell() again from inside afterChange re-triggers the hook. Pass a custom source string and check for it:

1
hot.addHook('afterChange', (changes, source) => {
2
  if (source === 'sync') {
3
    return;
4
  }
5

6
  // send `changes` to the server, then write the confirmed value back:
7
  hot.setDataAtCell(row, column, confirmedValue, 'sync');
8
});

Block changes with the beforeChange hook

Use beforeChange to validate or reject individual changes before they reach the grid. The hook receives the full batch of pending changes as an array of [row, prop, oldValue, newValue] tuples, so you can inspect and modify it in place.

The example below works on object data and cancels any change to the id property that isn’t a numeric string, using setDataAtRowProp()-style tuples:

1
hot.addHook('beforeChange', (changes, source) => {
2
  for (let i = changes.length - 1; i >= 0; i -= 1) {
3
    const [row, prop, oldValue, newValue] = changes[i];
4

5
    if (prop === 'id' && !/^\d+$/.test(String(newValue))) {
6
      changes[i] = null; // cancel this one change
7
    }
8
  }
9

10
  // return false; // cancels the entire batch instead
11
});

Setting an entry in changes to null cancels only that change; the rest of the batch still applies. Returning false from the hook cancels the whole batch instead. A change made through setDataAtRowProp() arrives with source === 'edit', the same as any other direct edit (see the source table above).

List of callbacks that operate on the source parameter:

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.

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

5
@Component({
6
  selector: 'example2-events-hooks',
7
  standalone: true,
8
  imports: [HotTableModule],
9
  template: ` <div>
10
    <hot-table [data]="data" [settings]="gridSettings"></hot-table>
11
  </div>`,
12
})
13
export class AppComponent implements AfterViewInit {
14
  @ViewChild(HotTableComponent, { static: false }) readonly hotTable!: HotTableComponent;
15

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

18
  data = [
19
    ['Tesla', 2017, 'black', 'black'],
20
    ['Nissan', 2018, 'blue', 'blue'],
21
    ['Chrysler', 2019, 'yellow', 'black'],
22
    ['Volvo', 2020, 'yellow', 'gray'],
23
  ];
24

25
  readonly gridSettings: GridSettings = {
26
    colHeaders: true,
27
    rowHeaders: true,
28
    height: 'auto',
29
    minSpareRows: 1,
30
    beforeChange: (changes: any, source: any) => {
31
      this.lastChange = changes;
32
    },
33
    autoWrapRow: true,
34
    autoWrapCol: true
35
  };
36

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

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

44
        if (!selection) return undefined;
45

46
        // Ignore header and corner selections (row or column index < 0)
47
        if (selection[0] < 0 || selection[1] < 0) return undefined;
48

49
        console.log(selection);
50

51
        // BACKSPACE or DELETE
52
        if (e.keyCode === 8 || e.keyCode === 46) {
53
          // remove data at cell, shift up
54
          hot.spliceCol(selection[1], selection[0], 1);
55
          e.preventDefault();
56
          this.lastChange = null;
57

58
          // block the default deletion behavior
59
          return false;
60
        }
61

62
        // ENTER
63
        if (e.keyCode === 13) {
64
          // if last change affected a single cell and did not change it's values
65
          if (
66
            this.lastChange &&
67
            this.lastChange.length === 1 &&
68
            this.lastChange[0][2] == this.lastChange[0][3]
69
          ) {
70
            hot.spliceCol(selection[1], selection[0], 0, '');
71
            // add new cell
72
            hot.selectCell(selection[0], selection[1]);
73
            // select new cell
74
            this.lastChange = null;
75

76
            // block the default Enter behavior
77
            return false;
78
          }
79
        }
80

81
        this.lastChange = null;
82

83
        return undefined;
84
      },
85
    });
86
  }
87
}
88
/* end-file */
89

90

91

92
/* file: app.config.ts */
93
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
94
import { registerAllModules } from 'handsontable/registry';
95
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
96

97
// register Handsontable's modules
98
registerAllModules();
99

100
export const appConfig: ApplicationConfig = {
101
  providers: [
102
    provideZoneChangeDetection({ eventCoalescing: true }),
103
    {
104
      provide: HOT_GLOBAL_CONFIG,
105
      useValue: { license: NON_COMMERCIAL_LICENSE } as HotGlobalConfig,
106
    },
107
  ],
108
};
109
/* end-file */

1
<div>
2
  <example2-events-hooks id="example2"></example2-events-hooks>
3
</div>

Core methods

Hooks

List of all Handsontable hooks

afterListen

afterUnlisten

Configuration options — see how hooks interact with grid configuration at initialization.
Saving data — a practical example of using the afterChange hook to persist edits to a backend.