Custom keyboard shortcuts

In this tutorial, you will register custom keyboard shortcuts in Handsontable using the ShortcutManager API. You will learn how to add shortcuts like Ctrl+D to duplicate rows and Ctrl+Enter to submit grid data without conflicting with existing browser or grid shortcuts.

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

5
/* start:skip-in-preview */
6
const employees = [
7
  { name: 'Ana García', department: 'Engineering', role: 'Senior Developer', salary: 95000, startDate: '2021-03-15' },
8
  { name: 'James Okafor', department: 'Marketing', role: 'Marketing Manager', salary: 82000, startDate: '2020-07-01' },
9
  { name: 'Li Wei', department: 'Engineering', role: 'Frontend Developer', salary: 78000, startDate: '2022-01-10' },
10
  { name: 'Priya Nair', department: 'HR', role: 'HR Specialist', salary: 68000, startDate: '2019-11-20' },
11
  { name: 'Carlos Mendes', department: 'Finance', role: 'Financial Analyst', salary: 88000, startDate: '2021-09-05' },
12
  { name: 'Fatima Al-Hassan', department: 'Engineering', role: 'Backend Developer', salary: 92000, startDate: '2020-04-18' },
13
  { name: 'Noah Kim', department: 'Design', role: 'UX Designer', salary: 75000, startDate: '2023-02-14' },
14
  { name: 'Sara Lindqvist', department: 'Marketing', role: 'Content Strategist', salary: 71000, startDate: '2019-06-30' },
15
];
16
/* end:skip-in-preview */
17

18
@Component({
19
  selector: 'example1-keyboard-shortcuts',
20
  standalone: true,
21
  imports: [HotTableModule],
22
  template: `
23
    <hot-table [data]="data" [settings]="gridSettings"></hot-table>
24
    <strong>Shortcut log:</strong>
25
    <table class="debug-table">
26
      <colgroup>
27
        <col style="width: 180px">
28
        <col>
29
      </colgroup>
30
      <tbody>
31
        <tr>
32
          <td>Last shortcut triggered</td>
33
          <td><code>{{ lastShortcut }}</code></td>
34
        </tr>
35
        <tr>
36
          <td>Last submission</td>
37
          <td><code>{{ lastSubmission }}</code></td>
38
        </tr>
39
      </tbody>
40
    </table>
41
  `,
42
})
43
export class AppComponent implements AfterViewInit, OnDestroy {
44
  @ViewChild(HotTableComponent, { static: false }) readonly hotTable!: HotTableComponent;
45

46
  private readonly ngZone = inject(NgZone);
47

48
  data = employees;
49
  lastShortcut = '—';
50
  lastSubmission = '—';
51

52
  readonly gridSettings: GridSettings = {
53
    colHeaders: ['Name', 'Department', 'Role', 'Salary', 'Start Date'],
54
    columns: [
55
      { data: 'name', type: 'text' },
56
      { data: 'department', type: 'text' },
57
      { data: 'role', type: 'text' },
58
      { data: 'salary', type: 'numeric', locale: 'en-US', numericFormat: { style: 'currency', currency: 'USD', minimumFractionDigits: 0, maximumFractionDigits: 0 } },
59
      { data: 'startDate', type: 'text' },
60
    ],
61
    rowHeaders: true,
62
    height: 'auto',
63
    width: '100%',
64
    autoWrapRow: true,
65
  };
66

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

70
    if (!hot) {
71
      return;
72
    }
73

74
    const gridContext = hot.getShortcutManager().getContext('grid');
75

76
    if (!gridContext) {
77
      return;
78
    }
79

80
    // Ctrl+D: duplicate the currently selected row
81
    gridContext.addShortcut({
82
      keys: [['Control', 'd']],
83
      group: 'customActions',
84
      runOnlyIf: () => hot.getSelected() !== undefined,
85
      callback: (event: Event) => {
86
        event.preventDefault();
87

88
        const selectedRange = hot.getSelectedRangeLast();
89

90
        if (!selectedRange) {
91
          return;
92
        }
93

94
        const row = selectedRange.from.row;
95
        const rowData = hot.getSourceDataAtRow(row) as Record<string, unknown>;
96

97
        hot.alter('insert_row_below', row);
98
        hot.populateFromArray(row + 1, 0, [Object.values(rowData)]);
99

100
        this.ngZone.run(() => { this.lastShortcut = 'Ctrl+D -- row duplicated'; });
101
      },
102
    });
103

104
    // Ctrl+Enter: submit the grid data
105
    gridContext.addShortcut({
106
      keys: [['Control', 'Enter']],
107
      group: 'customActions',
108
      runOnlyIf: () => true,
109
      callback: (event: Event) => {
110
        event.preventDefault();
111

112
        const data = hot.getData();
113
        const headers = hot.getColHeader() as string[];
114
        const rowCount = data.length;
115
        const timestamp = new Date().toLocaleTimeString();
116

117
        this.ngZone.run(() => {
118
          this.lastShortcut = 'Ctrl+Enter -- data submitted';
119
          this.lastSubmission = `[${timestamp}] Submitted ${rowCount} rows -- columns: ${headers.join(', ')}`;
120
        });
121
      },
122
    });
123
  }
124

125
  ngOnDestroy(): void {
126
    const hot = this.hotTable?.hotInstance;
127

128
    if (!hot) {
129
      return;
130
    }
131

132
    hot.getShortcutManager().getContext('grid')?.removeShortcutsByGroup('customActions');
133
  }
134
}
135
/* end-file */
136

137
/* file: app.config.ts */
138
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
139
import { registerAllModules } from 'handsontable/registry';
140
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
141

142
registerAllModules();
143

144
export const appConfig: ApplicationConfig = {
145
  providers: [
146
    provideZoneChangeDetection({ eventCoalescing: true }),
147
    {
148
      provide: HOT_GLOBAL_CONFIG,
149
      useValue: { license: NON_COMMERCIAL_LICENSE } as HotGlobalConfig,
150
    },
151
  ],
152
};
153
/* end-file */

1
<div>
2
  <example1-keyboard-shortcuts></example1-keyboard-shortcuts>
3
</div>

Overview

Difficulty: Beginner Time: ~15 minutes

Handsontable’s ShortcutManager API lets you register custom keyboard shortcuts that fire only when the grid has focus. This recipe shows how to add two common shortcuts: Ctrl+D to duplicate a selected row, and Ctrl+Enter to collect and submit the grid’s data.

What You’ll Build

A grid with two custom shortcuts:

Ctrl+D — duplicates the currently selected row and inserts the copy directly below it.
Ctrl+Enter — reads all grid data and displays a submission summary in the shortcut log.
A shortcut log table below the grid that shows the last shortcut triggered and the last submission.

Before you begin

This recipe requires no extra dependencies beyond Handsontable itself. You should be familiar with:

Creating a basic Handsontable instance.
Reading cell data with hot.getData() and hot.getSourceDataAtRow().
Modifying rows with hot.alter() and hot.populateFromArray().

Set up the grid

Import Handsontable, register all modules, and initialize the grid with your data.

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3

4
registerAllModules();
5

6
const container = document.querySelector('#example1');
7

8
const hot = new Handsontable(container, {
9
  data: employees,
10
  colHeaders: ['Name', 'Department', 'Role', 'Salary', 'Start Date'],
11
  columns: [
12
    { data: 'name', type: 'text' },
13
    { data: 'department', type: 'text' },
14
    { data: 'role', type: 'text' },
15
    { data: 'salary', type: 'numeric', locale: 'en-US', numericFormat: { style: 'currency', currency: 'USD', minimumFractionDigits: 0, maximumFractionDigits: 0 } },
16
    { data: 'startDate', type: 'text' },
17
  ],
18
  rowHeaders: true,
19
  height: 'auto',
20
  licenseKey: 'non-commercial-and-evaluation',
21
});

What’s happening:

registerAllModules() registers all built-in cell types, editors, renderers, and plugins — including the ShortcutManager.
The grid uses an array of objects as its data source. Each property maps to a column via the data key.

Access the ShortcutManager and grid context
```
1
const shortcutManager = hot.getShortcutManager();
2
const gridContext = shortcutManager.getContext('grid');
```
What’s happening:
- hot.getShortcutManager() returns the ShortcutManager instance attached to this grid.
- shortcutManager.getContext('grid') returns the 'grid' context — the context that is active whenever the grid has keyboard focus. Shortcuts registered here fire only while the user is interacting with the grid.
Why a context? Handsontable uses contexts to scope shortcuts. The 'grid' context is the default active context when the grid has focus. Other contexts (for example 'editor') become active when a cell editor is open, so your custom grid shortcuts do not interfere with text input.
Register Ctrl+D to duplicate a row
```
1
gridContext.addShortcut({
2
  keys: [['Control', 'd']],
3
  group: 'customActions',
4
  runOnlyIf: () => hot.getSelected() !== undefined,
5
  callback: (event) => {
6
    event.preventDefault();
7

8
    const selectedRange = hot.getSelectedRangeLast();
9

10
    if (!selectedRange) {
11
      return;
12
    }
13

14
    const row = selectedRange.from.row;
15
    const rowData = hot.getSourceDataAtRow(row);
16

17
    hot.alter('insert_row_below', row);
18
    hot.populateFromArray(row + 1, 0, [Object.values(rowData)]);
19

20
    lastShortcutEl.textContent = 'Ctrl+D -- row duplicated';
21
  },
22
});
```
What’s happening:
- keys: [['Control', 'd']] — an array of key combinations. Each inner array is one combination; multiple inner arrays mean “any of these combinations”. Key names match the KeyboardEvent.key property (case-insensitive, with Control, Alt, Shift, and Meta as modifiers).
- group: 'customActions' — a logical group name. Groups let you remove or disable multiple shortcuts at once.
- runOnlyIf: () => hot.getSelected() !== undefined — a guard function. The callback fires only when this function returns true. Here it ensures at least one cell is selected before the shortcut does anything.
- event.preventDefault() — prevents the browser’s default behavior for Ctrl+D (which bookmarks the page in some browsers).
- hot.getSelectedRangeLast() — returns a CellRange describing the last selection. .from.row gives the top row of that selection (visual index).
- hot.getSourceDataAtRow(row) — reads the raw source data object for that row, bypassing any column sorting or filtering.
- hot.alter('insert_row_below', row) — inserts a new empty row immediately below the selected row.
- hot.populateFromArray(row + 1, 0, [Object.values(rowData)]) — fills the new row with the original row’s values. populateFromArray expects a 2-D array, so wrap the flat values array in an outer array.
Register Ctrl+Enter to submit the grid data
```
1
gridContext.addShortcut({
2
  keys: [['Control', 'Enter']],
3
  group: 'customActions',
4
  runOnlyIf: () => true,
5
  callback: (event) => {
6
    event.preventDefault();
7

8
    const data = hot.getData();
9
    const headers = hot.getColHeader();
10
    const rowCount = data.length;
11
    const timestamp = new Date().toLocaleTimeString();
12

13
    lastShortcutEl.textContent = 'Ctrl+Enter -- data submitted';
14
    lastSubmissionEl.textContent = `[${timestamp}] Submitted ${rowCount} rows -- columns: ${headers.join(', ')}`;
15
  },
16
});
```
Where lastShortcutEl and lastSubmissionEl are references to the <code> cells in the shortcut log table. Acquire them once after Handsontable initializes:
```
1
const preview = container.closest('.hot-example-preview') ?? container.parentElement;
2
const lastShortcutEl = preview.querySelector('.last-shortcut');
3
const lastSubmissionEl = preview.querySelector('.last-submission');
```
What’s happening:
- keys: [['Control', 'Enter']] — fires on Ctrl+Enter. In a standard HTML form, Enter submits, but inside a data grid you often want to capture Ctrl+Enter for a deliberate “submit all” action.
- event.preventDefault() — in some browsers Ctrl+Enter can trigger form submission or other default behavior; this prevents it.
- hot.getData() — returns a 2-D array of all visible cell values (respecting column and row order after sorting or filtering).
- hot.getColHeader() — returns the current column header labels as an array.
- The summary is written to the shortcut log table below the grid. In a real application you would replace this with a fetch() call or a Redux action.

(Optional) Remove a built-in shortcut

If a built-in shortcut conflicts with your custom one, remove it before registering yours:

1
// Remove the built-in Delete key shortcut (clears cell content)
2
shortcutManager.getContext('grid').removeShortcutsByKeys([['Delete']]);

Why use removeShortcutsByKeys instead of overwriting? Handsontable checks for key conflicts at registration time. Removing the built-in shortcut first prevents a console warning and ensures only your handler runs.

The table below lists the most commonly overridden built-in shortcuts:

Keys	Default action
`Delete`	Clear cell content
`Backspace`	Clear cell content
`Enter`	Open cell editor / move down
`Tab`	Move focus to next cell
`Escape`	Cancel editing
`Control+A`	Select all cells
`Control+Z`	Undo
`Control+Y`	Redo
`Control+C`	Copy selection
`Control+V`	Paste

How It Works - Complete Flow

Grid renders — ShortcutManager initializes with the 'grid' context and all built-in shortcuts already registered.
User focuses the grid — the 'grid' context becomes active; your custom shortcuts are now listening.
User presses Ctrl+D — ShortcutManager matches the key combination against registered handlers. The runOnlyIf guard runs first. If a row is selected, the callback fires: the selected row is read, a new row is inserted below, and the copy is populated.
User presses Ctrl+Enter — ShortcutManager matches Ctrl+Enter, calls event.preventDefault(), reads hot.getData(), and writes a summary to the shortcut log table.
User focuses outside the grid — the 'grid' context deactivates; your shortcuts no longer fire.

What you learned

How to retrieve the ShortcutManager with hot.getShortcutManager().
How to target the 'grid' context with shortcutManager.getContext('grid').
How to register a custom shortcut with addShortcut({ keys, group, runOnlyIf, callback }).
How to guard shortcuts with runOnlyIf so they only fire when conditions are met.
How to duplicate a row using hot.alter() and hot.populateFromArray().
How to collect grid data with hot.getData() for a submit action.
How to prevent browser defaults with event.preventDefault().
How to remove a built-in shortcut with removeShortcutsByKeys().

Next steps

Explore the full Keyboard shortcuts guide to see all built-in shortcuts.
Use context.addShortcut with keys: [['Control', 'z'], ['Meta', 'z']] to support both Windows (Ctrl) and macOS (Cmd) modifiers in a single registration.
Register shortcuts in the 'editor' context to intercept key presses while a cell is being edited.
Combine runOnlyIf with hot.isEmptyRow() or custom selection checks to build context-sensitive shortcut menus.