Keyboard Shortcuts
Overview
This feature allows you to configure local and global keyboard shortcuts for your Electron application.
Example
Local Shortcuts
Local keyboard shortcuts are triggered only when the application is focused. To configure a local keyboard shortcut, you need to specify an accelerator property when creating a MenuItem within the Menu module.
Starting with a working application from the Quick Start Guide, update the main.js file with the following lines:
- index.html
- main.js
<!DOCTYPEhtml>
<html>
<head>
<metacharset="UTF-8">
<title>Hello World!</title>
<metahttp-equiv="Content-Security-Policy"content="script-src 'self''unsafe-inline';"/>
</head>
<body>
<h1>Hello World!</h1>
<p>Hit Alt+Shift+I on Windows, or Opt+Cmd+I on mac to see a message printed to the console.</p>
</body>
</html>
const{ app,BrowserWindow,Menu,MenuItem}=require('electron')
functioncreateWindow(){
const win =newBrowserWindow({
width:800,
height:600,
})
win.loadFile('index.html')
}
const menu =newMenu()
menu.append(newMenuItem({
label:'Electron',
submenu:[{
role:'help',
accelerator: process.platform==='darwin'?'Alt+Cmd+I':'Alt+Shift+I',
click:()=>{console.log('Electron rocks!')}
}]
}))
Menu.setApplicationMenu(menu)
app.whenReady().then(createWindow)
app.on('window-all-closed',()=>{
if(process.platform!=='darwin'){
app.quit()
}
})
app.on('activate',()=>{
if(BrowserWindow.getAllWindows().length===0){
createWindow()
}
})
NOTE: In the code above, you can see that the accelerator differs based on the user's operating system. For MacOS, it is
Alt+Cmd+I, whereas for Linux and Windows, it isAlt+Shift+I.
After launching the Electron application, you should see the application menu along with the local shortcut you just defined:
If you click Help or press the defined accelerator and then open the terminal that you ran your Electron application from, you will see the message that was generated after triggering the click event: "Electron rocks!".
Global Shortcuts
To configure a global keyboard shortcut, you need to use the globalShortcut module to detect keyboard events even when the application does not have keyboard focus.
Starting with a working application from the Quick Start Guide, update the main.js file with the following lines:
- index.html
- main.js
<!DOCTYPEhtml>
<html>
<head>
<metacharset="UTF-8">
<title>Hello World!</title>
<metahttp-equiv="Content-Security-Policy"content="script-src 'self''unsafe-inline';"/>
</head>
<body>
<h1>Hello World!</h1>
<p>Hit Alt+Ctrl+I on Windows or Opt+Cmd+I on Mac to see a message printed to the console.</p>
</body>
</html>
const{ app,BrowserWindow, globalShortcut }=require('electron')
functioncreateWindow(){
const win =newBrowserWindow({
width:800,
height:600,
})
win.loadFile('index.html')
}
app.whenReady().then(()=>{
globalShortcut.register('Alt+CommandOrControl+I',()=>{
console.log('Electron loves global shortcuts!')
})
}).then(createWindow)
app.on('window-all-closed',()=>{
if(process.platform!=='darwin'){
app.quit()
}
})
app.on('activate',()=>{
if(BrowserWindow.getAllWindows().length===0){
createWindow()
}
})
NOTE: In the code above, the
CommandOrControlcombination usesCommandon macOS andControlon Windows/Linux.
After launching the Electron application, if you press the defined key combination then open the terminal that you ran your Electron application from, you will see that Electron loves global shortcuts!
Shortcuts within a BrowserWindow
Using web APIs
If you want to handle keyboard shortcuts within a BrowserWindow, you can listen for the keyup and keydown DOM events inside the renderer process using the addEventListener() API.
- index.html
- main.js
- renderer.js
<!DOCTYPEhtml>
<html>
<head>
<metacharset="UTF-8">
<!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
<metahttp-equiv="Content-Security-Policy"content="default-src 'self'; script-src 'self'">
<metahttp-equiv="X-Content-Security-Policy"content="default-src 'self'; script-src 'self'">
<title>Hello World!</title>
</head>
<body>
<h1>Hello World!</h1>
<p>Hit any key with this window focused to see it captured here.</p>
<div><span>Last Key Pressed: </span><spanid="last-keypress"></span></div>
<scriptsrc="./renderer.js"></script>
</body>
</html>
// Modules to control application life and create native browser window
const{app,BrowserWindow}=require('electron')
const path =require('path')
functioncreateWindow(){
// Create the browser window.
const mainWindow =newBrowserWindow({
width:800,
height:600,
})
// and load the index.html of the app.
mainWindow.loadFile('index.html')
}
// This method will be called when Electron has finished
// initialization and is ready to create browser windows.
// Some APIs can only be used after this event occurs.
app.whenReady().then(()=>{
createWindow()
app.on('activate',function(){
// On macOS it's common to re-create a window in the app when the
// dock icon is clicked and there are no other windows open.
if(BrowserWindow.getAllWindows().length===0)createWindow()
})
})
// Quit when all windows are closed, except on macOS. There, it's common
// for applications and their menu bar to stay active until the user quits
// explicitly with Cmd + Q.
app.on('window-all-closed',function(){
if(process.platform!=='darwin') app.quit()
})
functionhandleKeyPress(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
trueindicates that the listener will always receive key presses before other listeners so they can't havestopPropagation()called on them.
Intercepting events in the main process
The before-input-event event is emitted before dispatching keydown and keyup events in the page. It can be used to catch and handle custom shortcuts that are not visible in the menu.
Starting with a working application from the Quick Start Guide, update the main.js file with the following lines:
- index.html
- main.js
<!DOCTYPEhtml>
<html>
<head>
<metacharset="UTF-8">
<title>Hello World!</title>
<metahttp-equiv="Content-Security-Policy"content="script-src 'self''unsafe-inline';"/>
</head>
<body>
<h1>Hello World!</h1>
<p>Hit Ctrl+I to see a message printed to the console.</p>
</body>
</html>
const{ app,BrowserWindow}=require('electron')
app.whenReady().then(()=>{
const win =newBrowserWindow({ width:800, height:600})
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()
}
})
})
After launching the Electron application, if you open the terminal that you ran your Electron application from and press Ctrl+I key combination, you will see that this key combination was successfully intercepted.
Using third-party libraries
If you don't want to do manual shortcut parsing, there are libraries that do advanced key detection, such as mousetrap. Below are examples of usage of the mousetrap running in the Renderer process:
Mousetrap.bind('4',()=>{console.log('4')})
Mousetrap.bind('?',()=>{console.log('show shortcuts!')})
Mousetrap.bind('esc',()=>{console.log('escape')},'keyup')
// combinations
Mousetrap.bind('command+shift+k',()=>{console.log('command shift k')})
// map multiple combinations to the same callback
Mousetrap.bind(['command+k','ctrl+k'],()=>{
console.log('command k or control k')
// return false to prevent default behavior and stop event from bubbling
returnfalse
})
// gmail style sequences
Mousetrap.bind('g i',()=>{console.log('go to inbox')})
Mousetrap.bind('* a',()=>{console.log('select all')})
// konami code!
Mousetrap.bind('up up down down left right left right b a enter',()=>{
console.log('konami code')
})
© GitHub Inc.
Licensed under the MIT license.
https://www.electronjs.org/docs/latest/tutorial/keyboard-shortcuts