Global Shortcuts

Overview 

The global keyboard shortcuts are triggered even if the application does not have the keyboard focus. You can use them to implement global hotkeys for your application.

To register the CommandOrControl+Shift+D global keyboard shortcut, you can use the following approach:

import { globalShortcut } from '@mobrowser/api';

const success = globalShortcut.register('CommandOrControl+Shift+D', () => {
  console.log('CommandOrControl+Shift+D has been pressed')
})

The function returns true if the shortcut has been registered successfully.

The shortcut registration may fail if the same global shortcut is already registered by this method or the given shortcut cannot be registered due to the operating system restrictions.

You can also check if a global keyboard shortcut is already registered:

if (globalShortcut.isRegistered('CommandOrControl+Shift+D')) {
  console.log('CommandOrControl+Shift+D is already registered')
}

To unregister a global keyboard shortcut, use the following approach:

globalShortcut.unregister('CommandOrControl+Shift+D')

When the application is closed, all registered global shortcuts are automatically unregistered.

Left and right Command keysmacOS 

Command and CommandOrControl match either Command key. To register a shortcut for a specific Command key, use LeftCommand (LeftCmd) or RightCommand (RightCmd). You can register the key on its own or combine it with Shift, Control, or Alt and one regular key:

import { globalShortcut } from '@mobrowser/api';

// Called when the right Command key is pressed.
globalShortcut.register('RightCommand', () => {
  toggleDictation()
})

// Called when K is pressed while the left Command key and Shift are held.
globalShortcut.register('LeftCommand+Shift+K', () => {
  performAction()
})

A standalone shortcut is triggered when the Command key is pressed. A combination is triggered when its regular key is pressed, and the Shift, Control, and Alt modifiers must match exactly. Key releases and auto-repeat are ignored.

Keep the following rules in mind:

• Use only one Command key in a shortcut.
• Left and right shortcuts can coexist, also with a standalone Command shortcut. If the user holds both Command keys, both shortcuts are triggered.
• In a combination with a regular key, a generic and a sided shortcut conflict. For example, if Cmd+K is registered, registering RightCmd+K returns false.
• These names can’t be used with media keys or in menu item shortcuts.

Unlike other global shortcuts, these key presses also reach the focused application. To receive them while your application is in the background, the application needs the Accessibility permission.

Shortcut format 

The shortcut is a string in the format 'CommandOrControl+Shift+F'.

Tokens are separated by + and are case-insensitive. The last token must be a key code. All preceding tokens must be modifiers. The only exception is a standalone left or right Command key shortcut on macOS.

Modifiers 

Named key codes 

Single-character key codes 

Any single ASCII character can be used as a key code directly, e.g. A–Z, 0–9, and punctuation such as ,, -, ., /, ;, =, [, \, ], `, and '. Characters that require Shift (e.g. !, @, #, $, %, ^, &, *, (, ), +, :, <, >, ?, ", {, |, }, ~, _) implicitly add the Shift modifier.