Custom shortcuts
Use the ShortcutManager API to add, remove, replace, or block keyboard shortcuts in Handsontable DataGrid.
-
Access the
ShortcutManagerAPI:hot.getShortcutManager(); -
Select a keyboard shortcut context, for example:
const gridContext = hot.getShortcutManager().getContext('grid'); -
Use the selected context’s methods. For example, to use the
addShortcut()method in thegridcontext: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:
-
Select a context in which you want to add a shortcut, for example:
const gridContext = hot.getShortcutManager().getContext('grid'); -
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.
import { useRef } from 'react';import { HotTable } from '@handsontable/react-wrapper';import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modulesregisterAllModules();
const ExampleComponent = () => { const hotRef = useRef(null);
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 afterInitCallback = () => { const hot = hotRef.current?.hotInstance;
if (!hot) { return; }
// get the `grid` context from the `ShortcutManager` API const gridContext = hot.getShortcutManager().getContext('grid');
if (!gridContext) { return; }
// 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); }, }); };
return ( <HotTable // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/ ref={hotRef} data={data} colHeaders={['SKU', 'Product', 'Quantity', 'Category']} columns={[{}, {}, { type: 'numeric' }, {}]} height="auto" afterInit={afterInitCallback} /> );};
export default ExampleComponent;import { useRef } from 'react';import { HotTable, HotTableRef } from '@handsontable/react-wrapper';import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modulesregisterAllModules();
const ExampleComponent = () => { const hotRef = useRef<HotTableRef>(null);
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 afterInitCallback = () => { const hot = hotRef.current?.hotInstance;
if (!hot) { return; }
// get the `grid` context from the `ShortcutManager` API const gridContext = hot.getShortcutManager().getContext('grid');
if (!gridContext) { return; }
// 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); }, }); };
return ( <HotTable // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/ ref={hotRef} data={data} colHeaders={['SKU', 'Product', 'Quantity', 'Category']} columns={[{}, {}, { type: 'numeric' }, {}]} height="auto" afterInit={afterInitCallback} /> );};
export default ExampleComponent;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):
-
Select a context in which you want to remove a keyboard shortcut.
-
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:
-
Select a context.
-
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:
-
Select a context in which you want to replace a keyboard shortcut.
-
Get the old keyboard shortcut, using the selected context’s
getShortcuts()method. -
Remove the old keyboard shortcut, using the selected context’s
removeShortcutsByKeys()method. -
Replace the
keysproperty of the old keyboard shortcut with your new array of keys. -
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:
<HotTable 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:
| 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).
addShortcut() parameters
The keys parameter:
- Accepts all the
KeyboardEvent.keykey names. - Accepts key names in both lowercase and uppercase (e.g., both
Enterandenterwork) - 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: