Custom shortcuts

Customize Handsontable’s keyboard shortcuts.

Overview

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

Tip

To use the Handsontable API, you'll need access to the Handsontable instance. You can do that by utilizing a reference to the HotTable component, and reading its hotInstance property.

For more information, see the Instance access page.

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:

• Get the name of the currently-active context: getActiveContextName()
• Switch to a different context: setActiveContextName()
• Get an already-registered context: getContext()
• Create and register a new context: addContext()

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 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:

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

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

API reference

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

APIs

ShortcutContext→

ShortcutManager→

Configuration options

enterBeginsEditing→

enterMoves→

tabMoves→

Core methods

getShortcutManager()→

isListening()→

listen()→

unlisten()→

Hooks

afterDocumentKeyDown→

beforeKeyDown→

Troubleshooting

Didn’t find what you need? Try this:

View related topics→

Report an issue→

Start a discussion→

Contact our technical support→