Hotkey API

New in version 13.0

TYPO3 provides the @typo3/backend/hotkeys.js module that allows developers to register custom keyboard shortcuts in the TYPO3 backend.

It is also possible and highly recommended to register hotkeys in a dedicated scope to avoid conflicts with other hotkeys, perhaps registered by other extensions.

The module provides an enum with common modifier keys: Ctrl, Meta, Alt, and Shift), and also a public property describing the common hotkey modifier based on the user's operating system: Cmd (Meta) on macOS, Ctrl on anything else (this can be normalized via Hotkeys.normalizedCtrlModifierKey. Using any modifier is optional, but highly recommended.

Hint

Note that on macOS, using the ModifierKeys.ALT to query a pressed key needs you to listen on the key that results in using this modifier. So, if you listen on:

[Hotkeys.normalizedCtrlModifierKey, ModifierKeys.ALT, 'e']

this will not work, because on macOS ALT+e results in €, and you would need to bind to:

[Hotkeys.normalizedCtrlModifierKey, ModifierKeys.ALT, '€']

instead. To make this work across different operating systems, it would be recommended to listen on both variants with distinct javascript callbacks executing the same action. Or, try avoiding to bind to ModifierKeys.ALT altogether.

A hotkey is registered with the register() method. The method takes three arguments:

hotkey

An array defining the keys that must be pressed.

handler

A callback that is executed when the hotkey is invoked.

options

An object that configures a hotkey's behavior:

scope: The scope a hotkey is registered in.

Note

TYPO3-specific hotkeys may be registered in the reserved all scope. When invoking a hotkey from a different scope, the all scope is handled in any case at first.
allowOnEditables: If false (default), handlers are not executed when an editable element is focussed.
allowRepeat: If false (default), handlers are not executed when the hotkey is pressed for a long time.
bindElement: If given, an aria-keyshortcuts attribute is added to the element. This is recommended for accessibility reasons.

Example

EXT:my_extension/Resources/Public/JavaScript/hotkey.js

import Hotkeys, {ModifierKeys} from '@typo3/backend/hotkeys.js';

Hotkeys.register([Hotkeys.normalizedCtrlModifierKey, ModifierKeys.SHIFT, 'e'], keyboardEvent => {
  console.log('Triggered on Ctrl/Cmd+Shift+E');
}, {
  scope: 'my-extension/module',
  bindElement: document.querySelector('.some-element')
});

// Get the currently active scope
const currentScope = Hotkeys.getScope();

// Make use of registered scope
Hotkeys.setScope('my-extension/module');