global-hotkey v0.0.12
global-hotkey
global-hotkey
is a Node.js module that allows you to register and handle global hotkeys on Windows. This module provides functionality to listen for key combinations and execute
specified callbacks when the keys are pressed. This package allows to listen and override Windows specific hotkeys like Win+Space.
Installation
To install global-hotkey
, use npm:
npm install global-hotkey
Build
If you are using Electron or need to rebuild native bindings, run:
electron-rebuild
Usage
IMPORTANT NOTE: This package will produce a bug when you lock the screen using Win+L. This will make the Win key stuck and every keyboard input after unlocking the screen will act like Win is pressed. To solve this, use the resetKeyPressed function and call it when the user logs out. To do so, use the Electron powerMonitor callbacks.
Here’s a basic example of how to use global-hotkey
in your Node.js application:
const globalHotkey = require('global-hotkey');
// Add a listener for META + V
globalHotkey.addListener({meta: true, keyCode: globalHotkey.V_KEY_CODES.V}, () => {
console.log('Hello from META + V');
});
// Start listening for hotkeys
globalHotkey.startListening();
Functions
globalHotkey.addListener(keyEvent, callback)
- keyEvent: An object specifying the key combination to listen for. Needs to include
keyCode
and atleast one ofctrl
,meta
andalt
.ctrl
(boolean):true
if Control key should be pressed.meta
(boolean):true
if Meta (Windows) key should be pressed.alt
(boolean):true
if Alt key should be pressed.shift
(boolean):true
if Shift key should be pressed.keyCode
(number): The virtual key code of the key to listen for.
- callback: A function that will be called when the key combination is pressed.
Returns a unique listener ID which can be used to remove the listener.
globalHotkey.removeListener(id)
- id: The listener ID returned from
addListener
.
Removes the specified listener.
globalHotkey.removeAllListeners()
Removes all event listener.
globalHotkey.startListening()
Starts the internal thread to listen for key events. Must be called to begin processing hotkey events.
globalHotkey.stopListening()
Stops the internal thread from listening for key events and cleans up resources.
Note
The event listeners do not have to be all set before starting to listen, but to avoid any issues it might be smart to stop listening while setting new hotkey listeners.
Test
Here’s an example test file to demonstrate how to use the global-hotkey
module:
const globalHotkey = require('global-hotkey');
// Add a listener for META + V
const listenerId = globalHotkey.addListener({
meta: true,
keyCode: globalHotkey.V_KEY_CODES.V
}, () => console.log('Hello from META + V'));
// Add a listener for ALT + SPACE
globalHotkey.addListener({
alt: true,
keyCode: globalHotkey.V_KEY_CODES.SPACE
}, () => console.log('Hello from ALT + SPACE'));
// Add a listener for CTRL + SHIFT + C
globalHotkey.addListener({
ctrl: true,
shift: true,
keyCode: globalHotkey.V_KEY_CODES.C
}, () => console.log('Hello from CTRL + C'));
// Remove the META + V listener
globalHotkey.removeListener(listenerId);
console.log('Starting thread...');
globalHotkey.startListening();
// Stop listening after 20 seconds
setTimeout(() => {
console.log('Stopping thread...');
globalHotkey.stopListening();
}, 20000);
KeyCodes
For valid key codes you can consult the Microsoft Documentation on Virtual Key Codes. This module
provides a typed constant object V_KEY_CODES
for easy access to the key codes based on their names as stated in the Microsoft documentation. For example:
V_KEY_CODES.SPACE
Additionally this module provides KEYBOARD_EVENT_CODE_TO_VKEY
, an object mapping the codes you will find
as the code property of KeyboardEvents. This will be helpful if you want to register hotkeys that were
specified by the user by means of a Keyboard Input. For Example:
KEYBOARD_EVENT_CODE_TO_VKEY['Space']
For the KeyboardEvent codes of specific keys, you can, for example, consult this website.
Issues
If you encounter any issues or have suggestions for improvements, please open an issue on our GitHub repository.
License
This module is licensed under the MIT License. See the LICENSE file for more details.
Support the Project
If you enjoy using this project or find it helpful, you can support its continued development by buying me a coffee!
Thank you for your support and for helping keep this project going!