React Data Grid Keyboard shortcuts

Use and manage Handsontable's keyboard shortcuts.

Table of contents

• Overview
• Default keyboard shortcuts
  • Navigation keyboard shortcuts
  • Selection keyboard shortcuts
  • Edition keyboard shortcuts
  • Plugin keyboard shortcuts
• Custom keyboard shortcuts
  • Keyboard shortcut contexts
  • Adding a custom keyboard shortcut
  • Removing a keyboard shortcut
  • Replacing a keyboard shortcut
  • Blocking a keyboard shortcut's actions
• Related API reference

Overview

You can navigate Handsontable similarly to Google Sheets or Microsoft Excel, using the default keyboard shortcuts.

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

• Add custom keyboard shortcuts
• Remove keyboard shortcuts
• Replace keyboard shortcuts
• Block keyboard shortcuts' actions

Default keyboard shortcuts

By default, Handsontable features the keyboard shortcuts listed below.

• Navigation keyboard shortcuts
• Selection keyboard shortcuts
• Edition keyboard shortcuts
• Plugin keyboard shortcuts

You can easily check if a keyboard shortcut's action is compatible with Microsoft Excel or Google Sheets:

• Compatible: ✓
• Not compatible: ✗

TIP

Handsontable doesn't detect data series (doesn't differentiate between blank cells and non-blank cells). For this reason, some keyboard shortcuts (e.g., Cmd + Arrow keys) may behave differently than in Microsoft Excel or Google Sheets in certain situations.

Navigation keyboard shortcuts

These keyboard shortcuts work when you navigate the grid. They come from Handsontable's Core, so they work out of the box, with no need for additional plugins.

Windows	macOS	Action	Excel	Sheets
Arrow keys	Arrow keys	Move one cell up, down, left, or right	✓	✓
Ctrl + ↑	Cmd + ↑	Move to the first cell of the current column	✓	✓
Ctrl + ↓	Cmd + ↓	Move to the last cell of the current column	✓	✓
Ctrl + ←	Cmd + ←	Move to the leftmost cell of the current row	✓	✓
Ctrl + →	Cmd + →	Move to the rightmost cell of the current row	✓	✓
Enter	Enter	Enter the editing mode of the active cell	✗	✓
Shift + Enter	Shift + Enter	Enter the editing mode of the active cell	✗	✓
F2	F2	Enter the editing mode of the active cell	✓	✓
Alphanumeric keys	Alphanumeric keys	Enter the editing mode of the active cell, and enter the pressed key's value into the cell	✓	✓
Tab	Tab	Move to the next cell* (if there's only one column available, move one cell down)	✓	✓
Shift + Tab	Shift + Tab	Move to the previous cell* (if there's only one column available, move one cell up)	✓	✓
Home	Home	Move to the first non-frozen cell of the current row*	✓	✓
Ctrl + Home	Cmd + Home	Move to the first non-frozen cell of the grid*	✗	✓
End	End	Move to the last non-frozen cell of the current row*	✗	✓
Ctrl + End	Cmd + End	Move to the last non-frozen cell of the grid*	✗	✓
Page Up	Page Up	Move one screen up	✓	✓
Page Down	Page Down	Move one screen down	✓	✓

^* This action depends on your layout direction.

Selection keyboard shortcuts

These keyboard shortcuts help you select cells. They come from Handsontable's Core, so they work out of the box, with no need for additional plugins.

Windows	macOS	Action	Excel	Sheets
Ctrl + A	Cmd + A	Select all cells and headers	✓	✓
Ctrl + Shift + ↑	Cmd + Shift + ↑	Extend the selection to the first cell of the current column**	✓	✓
Ctrl + Shift + ↓	Cmd + Shift + ↓	Extend the selection to the last cell of the current column**	✓	✓
Ctrl + Shift + ←	Cmd + Shift + ←	Extend the selection to the leftmost cell of the current row**	✓	✓
Ctrl + Shift + →	Cmd + Shift + →	Extend the selection to the rightmost cell of the current row**	✓	✓
Shift + Arrow keys	Shift + Arrow keys	Extend the selection by one cell	✓	✓
Shift + Home	Shift + Home	Extend the selection to the first non-frozen cell of the current row*	✓	✗
Shift + End	Shift + End	Extend the selection to the last non-frozen cell of the current row*	✗	✗
Shift + Page Up	Shift + Page Up	Extend the selection by one screen up	✓	✓
Shift + Page Down	Shift + Page Down	Extend the selection by one screen down	✓	✓
Ctrl + Enter	Cmd + Enter	Fill the selected range of cells with the value of the active cell	✗	✓
Delete	Delete	Clear the contents of the selected cells	✓	✓
Backspace	Backspace	Clear the contents of the selected cells	✓	✓

^* This action depends on your layout direction.
^** In case of multiple selection layers, only the last selection layer gets extended.

Edition keyboard shortcuts

These keyboard shortcuts work when you're editing a cell's contents. They come from Handsontable's Core, so they work out of the box, with no need for additional plugins.

Windows	macOS	Action	Excel	Sheets
Arrow keys	Arrow keys	Move the cursor through the text	✓	✓
Alphanumeric keys	Alphanumeric keys	Enter the pressed key's value into the cell	✓	✓
Enter	Enter	Complete the cell entry and move to the cell below	✓	✓
Shift + Enter	Shift + Enter	Complete the cell entry and move to the cell above	✓	✓
Tab	Tab	Complete the cell entry and move to the next cell*	✓	✓
Shift + Tab	Shift + Tab	Complete the cell entry and move to the previous cell*	✓	✓
Delete	Delete	Delete one character after the cursor*	✓	✓
Backspace	Backspace	Delete one character before the cursor*	✓	✓
Home	Home	Move the cursor to the beginning of the text*	✓	✓
End	End	Move the cursor to the end of the text*	✓	✓
Ctrl + Arrow keys	Cmd + Arrow keys	Move the cursor to the beginning or to the end of the text	✓	✓
Ctrl + Shift + Arrow keys	Cmd + Shift + Arrow keys	Extend the selection to the beginning or to the end of the text	✓	✓
Page Up	Page Up	Complete the cell entry and move one screen up	✓	✓
Page Down	Page Down	Complete the cell entry and move one screen down	✓	✓
Alt + Enter	Option + Enter	Insert a line break	✗	✓
Ctrl + Enter	Ctrl / Cmd + Enter	Insert a line break	✗	✓
Escape	Escape	Cancel the cell entry and exit the editing mode	✓	✓

^* This action depends on your layout direction.

Checkbox editor keyboard shortcuts

These keyboard shortcuts work in the checkbox cell editor.

Windows	macOS	Action	Excel	Sheets
Space	Space	Check or uncheck the checkbox	✗	✓
Enter	Enter	Check or uncheck the checkbox	✗	✓
Delete	Delete	Uncheck the checkbox	✗	✓
Backspace	Backspace	Uncheck the checkbox	✗	✓

handsontable editor keyboard shortcuts

These keyboard shortcuts work in the handsontable cell editor.

Windows	macOS	Action	Excel	Sheets
↑	↑	Move to the cell above the active cell	✗	✗
↓	↓	Move to the cell below the active cell	✗	✗

Plugin keyboard shortcuts

These keyboard shortcuts work with particular plugins.

Clipboard keyboard shortcuts

These keyboard shortcuts work when the CopyPaste plugin is enabled.

Windows	macOS	Action	Excel	Sheets
Ctrl + X	Cmd + X	Cut the contents of the selected cells to the system clipboard	✓	✓
Ctrl + C	Cmd + C	Copy the contents of the selected cells to the system clipboard	✓	✓
Ctrl + V	Cmd + V	Paste from the system clipboard	✓	✓

Cell merging keyboard shortcuts

These keyboard shortcuts work when the MergeCells plugin is enabled.

Windows	macOS	Action	Excel	Sheets
Ctrl + M	Ctrl + M	Merge or unmerge the selected cells	✗	✗

Undo and redo keyboard shortcuts

These keyboard shortcuts work when the UndoRedo plugin is enabled.

Windows	macOS	Action	Excel	Sheets
Ctrl + Z	Cmd + Z	Undo the last action	✓	✓
Ctrl + Y	Cmd + Y	Redo the last action	✓	✓
Ctrl + Shift + Z	Cmd + Shift + Z	Redo the last action	✓	✓

Context menu keyboard shortcuts

These keyboard shortcuts work in context menus. To activate them, enable the ContextMenu plugin.

Windows	macOS	Action	Excel	Sheets
Arrow keys	Arrow keys	Move one available menu item up, down, left, or right	✓	✓
Page Up	Page Up	Move to the first visible item of the context menu or submenu	✓	✗
Page Down	Page Down	Move to the last visible item of the context menu or submenu	✓	✗
Escape	Escape	Close the context menu or submenu	✓	✓
Enter	Enter	Run the action of the selected menu item	✓	✗

Custom keyboard shortcuts

You can 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 Methods 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',
     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.

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

Adding 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',
     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)

   TIP

   Using the Alt (Option ⌥) modifier key

   Alt (Option ⌥) is often used for typing special characters (e.g., letters wich diacritical marks), and its behavior may vary depending on the user's language and keyboard settings.

   To properly use Alt (Option ⌥) in your shortcut, you may need to pass language-specific signs (such as à or ś) to the keys parameter.

Adding 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',
  runOnlyIf: () => hot.getSelected() !== void 0,
  keys: [['enter']],
  callback: () => {},
});

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

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

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

Blocking 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;
    }
  }}
/>

Related API reference

• APIs:
  • ShortcutContext
  • ShortcutManager
• Configuration options:
  • enterBeginsEditing
  • enterMoves
  • tabMoves
• Core methods:
  • getShortcutManager()
  • isListening()
  • listen()
  • unlisten()
• Hooks:
  • afterDocumentKeyDown
  • beforeKeyDown