/ S

JavaScript Data Grid Custom shortcuts

Customize Handsontable's keyboard shortcuts.

In this article

Overview

You can completely customize your keyboard shortcuts, using the ShortcutManager API:

  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: () => {},
});

Keyboard shortcut contexts

Every keyboard action is registered in a particular context:

Context Description Type
grid Activates when the user navigates the data grid (initial context) Built-in
editor Activates when the user opens a cell editor Built-in
menu Activates when the user opens a cell's context menu Built-in
Custom Your custom context Custom

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

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: () => {},
});

    The keys parameter:

    • Accepts all the KeyboardEvent.key (opens new window) 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)

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() !== void 0,
  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() !== void 0;
  },
  keys: [['F2']],
  callback: () => {
    if (hot.getActiveEditor().cellProperties.type === 'numeric') {
      return false; // the `F2` shortcut won't work for `numeric` cells
    }

    // another action
  },
});

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');

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;
  }
});

API reference

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

Troubleshooting

Didn't find what you need? Try this:

← Searching values →