electron/docs/tutorial/keyboard-shortcuts.md

title	description	slug	hide_title
Keyboard Shortcuts	Define accelerator strings for local and global keyboard shortcuts	keyboard-shortcuts	false

Keyboard Shortcuts

Accelerators

Accelerators are strings that can be used to represent keyboard shortcuts throughout your Electron. These strings can contain multiple modifiers keys and a single key code joined by the + character.

Note

Accelerators are case-insensitive.

Available modifiers

• Command (or Cmd for short)
• Control (or Ctrl for short)
• CommandOrControl (or CmdOrCtrl for short)
• Alt
• Option
• AltGr
• Shift
• Super (or Meta as alias)

Available key codes

• 0 to 9
• A to Z
• F1 to F24
• Various Punctuation: ), !, @, #, $, %, ^, &, *, (, :, ;, :, +, =, <, ,, _, -, >, ., ?, /, ~, `, {, ], [, |, \, }, "
• Plus
• Space
• Tab
• Capslock
• Numlock
• Scrolllock
• Backspace
• Delete
• Insert
• Return (or Enter as alias)
• Up, Down, Left and Right
• Home and End
• PageUp and PageDown
• Escape (or Esc for short)
• VolumeUp, VolumeDown and VolumeMute
• MediaNextTrack, MediaPreviousTrack, MediaStop and MediaPlayPause
• PrintScreen
• NumPad Keys
  • num0 - num9
  • numdec - decimal key
  • numadd - numpad + key
  • numsub - numpad - key
  • nummult - numpad * key
  • numdiv - numpad ÷ key

Cross-platform modifiers

Many modifier accelerators map to different keys between operating systems.

Modifier	macOS	Windows and Linux
CommandOrControl	Command (⌘)	Control
Command	Command (⌘)	N/A
Control	Control (^)	Control
Alt	Option (⌥)	Alt
Option	Option (⌥)	N/A
Super (Meta)	Command (⌘)	Windows (⊞)

Important

• On Linux and Windows, the Command modifier does not have any effect. In general, you should use the CommandOrControl modifier instead, which represents ⌘ Cmd on macOS and Ctrl on Linux and Windows.
• Use Alt instead of Option. The ⌥ Opt key only exists on macOS, whereas the Alt will map to the appropriate modifier on all platforms.

Examples

Here are some examples of cross-platform Electron accelerators for common editing operations:

• Copy: CommandOrControl+C
• Paste: CommandOrControl+V
• Undo: CommandOrControl+Z
• Redo: CommandOrControl+Shift+Z

Local shortcuts

Local keyboard shortcuts are triggered only when the application is focused. These shortcuts map to specific menu items within the app's main application menu.

To define a local keyboard shortcut, you need to configure the accelerator property when creating a MenuItem. Then, the click event associated to that menu item will trigger upon using that accelerator.

const { dialog, Menu, MenuItem } = require('electron/main')

const menu = new Menu()

// The first submenu needs to be the app menu on macOS
if (process.platform === 'darwin') {
  const appMenu = new MenuItem({ role: 'appMenu' })
  menu.append(appMenu)
}

// highlight-start
const submenu = Menu.buildFromTemplate([{
  label: 'Open a Dialog',
  click: () => dialog.showMessageBox({ message: 'Hello World!' }),
  accelerator: 'CommandOrControl+Alt+R'
}])
menu.append(new MenuItem({ label: 'Custom Menu', submenu }))
// highlight-end

Menu.setApplicationMenu(menu)

In the above example, a native "Hello World" dialog will open when pressing ⌘ Cmd+⌥ Opt+R on macOS or Ctrl+Alt+R on other platforms.

Tip

Accelerators can work even when menu items are hidden. On macOS, this feature can be disabled by setting acceleratorWorksWhenHidden: false when building a MenuItem.

Tip

On Windows and Linux, the registerAccelerator property of the MenuItem can be set to false so that the accelerator is visible in the system menu but not enabled.

Global shortcuts

Global keyboard shortcuts work even when your app is out of focus. To configure a global keyboard shortcut, you can use the globalShortcut.register function to specify shortcuts.

const { dialog, globalShortcut } = require('electron/main')

globalShortcut.register('CommandOrControl+Alt+R', () => {
  dialog.showMessageBox({ message: 'Hello World!' })
})

To later unregister a shortcut, you can use the globalShortcut.unregisterAccelerator function.

const { globalShortcut } = require('electron/main')

globalShortcut.unregister('CommandOrControl+Alt+R')

Warning

On macOS, there's a long-standing bug with globalShortcut that prevents it from working with keyboard layouts other than QWERTY (electron/electron#19747).

Shortcuts within a window

In the renderer process

If you want to handle keyboard shortcuts within a BaseWindow, you can listen for the keyup and keydown DOM Events inside the renderer process using the addEventListener API.

function handleKeyPress (event) {
  // You can put code here to handle the keypress.
  document.getElementById('last-keypress').innerText = event.key
  console.log(`You pressed ${event.key}`)
}

window.addEventListener('keyup', handleKeyPress, true)

Note

The third parameter true indicates that the listener will always receive key presses before other listeners so they can't have stopPropagation() called on them.

Intercepting events in the main process

The before-input-event event is emitted before dispatching keydown and keyup events in the renderer process. It can be used to catch and handle custom shortcuts that are not visible in the menu.

const { app, BrowserWindow } = require('electron/main')

app.whenReady().then(() => {
  const win = new BrowserWindow()

  win.loadFile('index.html')
  win.webContents.on('before-input-event', (event, input) => {
    if (input.control && input.key.toLowerCase() === 'i') {
      console.log('Pressed Control+I')
      event.preventDefault()
    }
  })
})