Skip to content

Custom shortcuts

Use the ShortcutManager API to add, remove, replace, or block keyboard shortcuts in Handsontable DataGrid.

  1. Access the ShortcutManager API:

    hot.getShortcutManager();
  2. Select a keyboard shortcut context, for example:

    const gridContext = hot.getShortcutManager().getContext('grid');
  3. Use the selected context’s methods. For example, to use the addShortcut() method in the grid context:

    const gridContext = hot.getShortcutManager().getContext('grid');
    gridContext.addShortcut({
    group: 'group_ID', // a string value; the user can decide on its name.
    // Each shortcut should be assigned to the group.
    keys: [['enter']],
    callback: () => {},
    });

Add a custom keyboard shortcut

To add a custom keyboard shortcut:

  1. Select a context in which you want to add a shortcut, for example:

    const gridContext = hot.getShortcutManager().getContext('grid');
  2. Using the selected context’s addShortcut() method, add your keyboard shortcut:

    const gridContext = hot.getShortcutManager().getContext('grid');
    gridContext.addShortcut({
    group: 'group_ID', // a string value; the user can decide on its name.
    // Each shortcut should be assigned to the group.
    keys: [['enter']],
    callback: () => {},
    });

Try it out

The example below registers a custom keyboard shortcut in the grid context, using the addShortcut() method. Select a cell and press Control/Cmd + Enter to insert a new row below it.

JavaScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modules
registerAllModules();
const data = [
['SKU-4821', 'Wireless Mouse', 128, 'Electronics'],
['SKU-0093', 'Desk Lamp', 42, 'Home Goods'],
['SKU-7734', 'USB-C Cable', 310, 'Electronics'],
['SKU-2210', 'Notebook Set', 87, 'Office Supplies'],
['SKU-5567', 'Water Bottle', 156, 'Outdoor'],
];
const container = document.querySelector('#example1');
const hot = new Handsontable(container, {
data,
colHeaders: ['SKU', 'Product', 'Quantity', 'Category'],
columns: [{}, {}, { type: 'numeric' }, {}],
height: 'auto',
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
// get the `grid` context from the `ShortcutManager` API
const gridContext = hot.getShortcutManager().getContext('grid');
if (gridContext) {
// register a custom keyboard shortcut in the `grid` context:
// pressing Control/Meta+Enter inserts a new row below the selected cell
gridContext.addShortcut({
keys: [['control/meta', 'enter']],
group: 'insertRowBelow',
callback: () => {
const selected = hot.getSelectedRangeLast();
if (!selected || selected.highlight.row === null) {
return;
}
hot.alter('insert_row_below', selected.highlight.row);
},
});
}
TypeScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modules
registerAllModules();
const data: (string | number)[][] = [
['SKU-4821', 'Wireless Mouse', 128, 'Electronics'],
['SKU-0093', 'Desk Lamp', 42, 'Home Goods'],
['SKU-7734', 'USB-C Cable', 310, 'Electronics'],
['SKU-2210', 'Notebook Set', 87, 'Office Supplies'],
['SKU-5567', 'Water Bottle', 156, 'Outdoor'],
];
const container: Element = document.querySelector('#example1')!;
const hot = new Handsontable(container, {
data,
colHeaders: ['SKU', 'Product', 'Quantity', 'Category'],
columns: [{}, {}, { type: 'numeric' }, {}],
height: 'auto',
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
// get the `grid` context from the `ShortcutManager` API
const gridContext = hot.getShortcutManager().getContext('grid');
if (gridContext) {
// register a custom keyboard shortcut in the `grid` context:
// pressing Control/Meta+Enter inserts a new row below the selected cell
gridContext.addShortcut({
keys: [['control/meta', 'enter']],
group: 'insertRowBelow',
callback: () => {
const selected = hot.getSelectedRangeLast();
if (!selected || selected.highlight.row === null) {
return;
}
hot.alter('insert_row_below', selected.highlight.row);
},
});
}

Add a conditional keyboard action

To make a keyboard action run on a certain condition, set the runOnlyIf parameter to a function:

const gridContext = hot.getShortcutManager().getContext('grid');
gridContext.addShortcut({
group: 'group_ID', // a string value; the user can decide on its name.
// Each shortcut should be assigned to the group.
runOnlyIf: () => hot.getSelected() !== undefined,
keys: [['enter']],
callback: () => {},
});

Set the order of keyboard actions

You can assign multiple actions to a single keyboard shortcut.

By default, when you assign a new action, it runs after any other actions that were assigned previously. To set your own order of actions, use the position and relativeToGroup parameters of the addShortcut() method:

const gridContext = hot.getShortcutManager().getContext('grid');
gridContext.addShortcut({
group: 'customNumericEditor',
position: 'before',
relativeToGroup: 'editorManager.handlingEditor',
runOnlyIf: () => hot.getSelected() !== undefined,
keys: [['F2']],
callback: () => {
if (hot.getActiveEditor().cellProperties.type === 'numeric') {
return false; // the `F2` shortcut won't work for `numeric` cells
}
// another action
},
});

A new action goes next to the first action of the relativeToGroup group. When you add several actions next to the same group, the newest one runs first.

Remove a keyboard shortcut

To remove a keyboard shortcut (e.g., one of the default keyboard shortcuts):

  1. Select a context in which you want to remove a keyboard shortcut.

  2. Use the selected context’s removeShortcutsByKeys() method.

    const gridContext = hot.getShortcutManager().getContext('grid');
    gridContext.removeShortcutsByKeys(['enter']);

To remove all keyboard shortcuts registered in a certain group:

  1. Select a context.

  2. Use the selected context’s removeShortcutsByGroup() method.

    const gridContext = hot.getShortcutManager().getContext('grid');
    gridContext.removeShortcutsByGroup('group_ID');

Remove the copy, cut, and paste shortcuts

The grid context registers Ctrl/Cmd + C, X, and V. These shortcuts do nothing on their own, because the browser runs the action. When you remove one, the CopyPaste plugin cancels that exact key combination, so Ctrl/Cmd + C, X, or V no longer copies, cuts, or pastes.

const gridContext = hot.getShortcutManager().getContext('grid');
gridContext.removeShortcutsByKeys(['control/meta', 'c']);

Only these three key combinations stop working. Handsontable treats Ctrl and Cmd as the same key, so Ctrl + Cmd + C on macOS and Ctrl + Win + C on Windows are cancelled too. Other native clipboard keys are not blocked, for example Ctrl/Cmd + Shift + V, Shift + Insert, Ctrl + Insert, and Shift + Delete.

The context menu items and the copy(), cut(), and paste() methods keep working. The keyboard also keeps working inside an open cell editor, including the editor’s text area when you use imeFastEdit, and inside your application’s own fields.

:::: tip

Moving a clipboard shortcut to other keys, as in Replace a keyboard shortcut, leaves the original key combination without a shortcut. The plugin then cancels it. To keep the original key working, add the shortcut again with the same keys, a callback that does nothing, and preventDefault: false. To turn the key off, remove the shortcut and don’t add it back.

::::

Remove the select-all shortcut

Ctrl/Cmd + A is a grid shortcut that selects all cells. When you remove it, Handsontable no longer handles the key combination. The browser’s native select-all runs instead. It selects the text on the page, or the text of the focused field. With imeFastEdit, the focused field is the editor’s hidden text area, so the page text stays unselected.

To block select-all completely, replace the shortcut with one whose callback does nothing. Leave the preventDefault option at its default value (true), so the browser does not select the page text either:

const gridContext = hot.getShortcutManager().getContext('grid');
gridContext.removeShortcutsByKeys(['control/meta', 'a']);
gridContext.addShortcuts([{
keys: [['control/meta', 'a']],
callback: () => {},
group: 'myShortcuts',
}]);

Replace a keyboard shortcut

To replace a keyboard shortcut:

  1. Select a context in which you want to replace a keyboard shortcut.

  2. Get the old keyboard shortcut, using the selected context’s getShortcuts() method.

  3. Remove the old keyboard shortcut, using the selected context’s removeShortcutsByKeys() method.

  4. Replace the keys property of the old keyboard shortcut with your new array of keys.

  5. Add your new keyboard shortcut, using the selected context’s addShortcuts() method.

    const gridContext = hot.getShortcutManager().getContext('grid');
    const undoShortcut = gridContext.getShortcuts(['control/meta', 'z']);
    gridContext.removeShortcutsByKeys(['control/meta', 'z']);
    undoShortcut.map((shortcut) => {
    shortcut.keys = [['shift', 'control/meta', 'z']];
    });
    gridContext.addShortcuts(undoShortcut);

Block a keyboard shortcut’s actions

To block a keyboard shortcut’s actions, return false in the beforeKeyDown hook’s callback:

hot.addHook('beforeKeyDown', (event) => {
// the `Enter` shortcut won't work
if (event.key === 'enter') {
return false;
}
});

Result

After completing these steps, you have custom keyboard shortcuts registered in the target context. The shortcuts trigger your callbacks when the user presses the configured key combination, and only when the specified context is active.

Reference

Keyboard shortcut contexts

Every keyboard action is registered in a particular context:

ContextDescriptionType
gridActivates when the user navigates the data grid (initial context)Built-in
editorActivates when the user opens a cell editorBuilt-in
menuActivates when the user opens a cell’s context menuBuilt-in
CustomYour custom contextCustom

When the user interacts with the keyboard, only actions registered for the currently-active context are executed. Only one context is active at a time.

Manage keyboard shortcut contexts

Using the ShortcutManager API methods, you can:

For example: if you’re using a complex custom editor, you can create a new shortcut context to navigate your editor’s UI with the arrow keys (normally, the arrow keys would navigate the grid instead).

addShortcut() parameters

The keys parameter:

  • Accepts all the KeyboardEvent.key key names.
  • Accepts key names in both lowercase and uppercase (e.g., both Enter and enter work)
  • Handles key-name discrepancies between browsers (e.g., both 'Spacebar' and ' ' work)
  • Accepts key names in any order (e.g., both [['control', 'a']] and [['a', 'control']]) work)

The control/meta key name is specific to Handsontable. It matches Control on Windows and Linux, and Meta on macOS. For arrow keys, use KeyboardEvent.key names such as ArrowLeft, not display glyphs such as ←.

API reference

For the list of options, methods, and Handsontable hooks related to keyboard navigation, see the following API reference pages:

APIs

Configuration options

Core methods

Hooks

Troubleshooting

Didn’t find what you need? Try this: