This page covers a next version of Handsontable, and is not published yet.

This page covers a non-latest version of Handsontable.

# Keyboard shortcuts

Use and manage Handsontable's keyboard shortcuts.

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

# Default keyboard shortcuts

By default, Handsontable features the keyboard shortcuts listed below.

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.

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.

  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:

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:

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