Hotkey API¶

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. Using any modifier is optional, but highly recommended.

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.

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

Hotkeys.register([Hotkeys.normalizedCtrlModifierKey, ModifierKeys.ALT, 'e'], keyboardEvent => {
  console.log('Triggered on Ctrl/Cmd+Alt+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');