Node Hotkeys
Handle hotkeys on NodeJS easily.
Registering hotkeys
Simple use
const hotkeys = require('node-hotkeys');
hotkeys.on({
hotkeys: 'ctrl + a',
matchAllModifiers: true,
callback: function (hotkey) {
console.log("Activated:", hotkey);
}
});
If ctrl + a is pressed, the output will be:
Activated: ctrl + a
Multiple hotkeys
Separate the hotkeys using comma:
hotkeys.on({
hotkeys: 'alt + a, shift + a, ctrl + a',
matchAllModifiers: true,
callback: function (hotkey) {
console.log("Activated:", hotkey);
}
});
If any of the registered hotkeys are pressed, the output will be:
Activated: alt + a, shift + a, ctrl + a
Triggering multiple hotkeys
By adding the option triggerAll
we can call the callback function for each of the hotkeys pressed:
hotkeys.on({
hotkeys: 'alt + a, shift + a, ctrl + a',
matchAllModifiers: true,
triggerAll: true,
callback: function (hotkey) {
console.log("Activated:", hotkey);
}
});
If shift + a is pressed and then alt + a, the output will be:
Activated: shift + a
Activated: alt + a
Matching only the required modifiers
If we set matchAllModifiers
to false
then we'll be able to detect hotkeys that may have been pressed accompanied by other modifiers:
hotkeys.on({
hotkeys: 'ctrl + a, a',
matchAllModifiers: false,
triggerAll: true,
callback: function (hotkey) {
console.log("Activated:", hotkey);
}
});
If ctrl + a is pressed, the output will be:
Activated: ctrl + a
Activated: a
And if shift + a is pressed, the output will be:
Activated: a
PS: the modifiers are alt
, shift
and ctrl
.
Matching capitalization
If you would like to differentiate uppercase and lowercase letters, add the capitalization
option:
hotkeys.on({
hotkeys: 'ctrl + a, ctrl + A',
capitalization: true,
triggerAll: true,
callback: function (hotkey) {
console.log("Activated:", hotkey);
}
});
If you have caps lock disabled and press ctrl + a, the output will be:
Activated: ctrl + a
If you have caps lock disabled and press ctrl + shift + a, the output will be:
Activated: ctrl + A
If you have caps lock enabled and press ctrl + a, the output will be:
Activated: ctrl + A
And if you have caps lock enabled and press ctrl + shift + a, the output will be:
Activated: ctrl + a
Special cases
hotkeys.on({
hotkeys: 'shift + plus, enter, space, tab, esc, backspace',
triggerAll: true,
callback: function (hotkey) {
console.log("Activated:", hotkey);
}
});
If we press those keys in that order, the output will be:
Activated: shift + plus
Activated: enter
Activated: space
Activated: tab
Activated: esc
Activated: backspace
Detecting special keys
Some keys do not have a character representation, thus they can only be detected using keydown
events, which you can turn on by setting the option useKeyDown
to true
:
hotkeys.on({
hotkeys: 'left, up, right, down',
matchAllModifiers: true,
triggerAll: true,
useKeyDown: true,
callback: function (hotkey) {
console.log("Arrow:", hotkey);
}
});
If we press those keys in that order, the output will be:
Arrow: left
Arrow: up
Arrow: right
Arrow: down
Other special keys: capslock
, pgup
, pgdn
, end
, home
, prtsc
, insert
, delete
, cmd
, F1
, F2
, F3
, F4
, F5
, F6
, F7
, F8
, F9
, F10
, F11
, F12
.
Split key
The split key is used to combine keys in order to define the hotkey, the default split key is +
. But it can be changed using the splitKey
option:
hotkeys.on({
hotkeys: 'shift - +',
splitKey: '-',
callback: function (hotkey) {
console.log("Activated:", hotkey);
}
});
If we press shift and +, the output will be:
Activated: shift - +
Removing hotkeys
The following method has support to the same options of the method on()
used to register the hotkeys.
hotkeys.remove({ hotkeys: "ctrl + a" });
PS: when removing hotkeys all modifiers will always be checked and only if they match that the hotkey will be removed. So matchAllModifiers
is automatically set true
.
Detecting any hotkeys
It is also possible to detect what combination of keys the user pressed by using the method getNextHotkey
:
(async () => {
while (true) {
let hotkeyStr = await hotkeys.getNextHotkey(false);
console.log("Detected:", hotkeyStr);
}
})();
The code above prints in the console every hotkey pressed by the user, it can be used, for instance, when asking for the user to choose a custom hotkey. The method getNextHotkey
receives a boolean
parameter that determines whether to listen to hotkeys from keydown
events (when true
) or only keypress
events (when false
). It also returns a Promise
that will be resolved with the hotkey string definition that the user chose. So if you press alt + shift + y with caps lock disabled, the output will be:
Detected: alt + shift + Y
Access the IOHook instance
hotkeys.iohook
More information about IOHook on this link.
Debug hotkeys being used
Example of use:
hotkeys.on({
hotkeys: 'alt + a, shift + a',
matchAllModifiers: true,
triggerAll: true,
callback: function (hotkey) { }
});
hotkeys.on({
hotkeys: 'ctrl + h, H',
capitalization: true,
callback: function (hotkey) { }
});
hotkeys.logRegisteredHotkeys();
Output:
[{
"hotkeyStr": "alt + a",
"shiftKey": false,
"altKey": true,
"ctrlKey": false,
"matchAllModifiers": true,
"rawcode": 65
}, {
"hotkeyStr": "shift + a",
"shiftKey": true,
"altKey": false,
"ctrlKey": false,
"matchAllModifiers": true,
"rawcode": 65
}, {
"hotkeys": [{
"hotkeyStr": "ctrl + h",
"shiftKey": false,
"altKey": false,
"ctrlKey": true,
"matchAllModifiers": false,
"keychar": 104
}, {
"hotkeyStr": "H",
"shiftKey": false,
"altKey": false,
"ctrlKey": false,
"matchAllModifiers": false,
"keychar": 72
}],
"hotkeyStr": "ctrl + h, H"
}]
Using Debounce Listeners
The debounce
method can register a callback to be called whenever the user presses keys or types some text. You must define a debounce time in milliseconds and the callback that will receive the content typed as a string and the KeypressEvent
s array with each key pressed. The string returned by this method is a key that identifies the registered debounce listener so that you can remove it later using removeDebounce
.
Definition:
debounce (ms: number, callback: (string, KeypressEvent[]) => void): string
Example of use:
const hotkeys = require('node-hotkeys');
const key = hotkeys.debounce(500, (value, events) => {
console.log("INPUT:", value);
});
Removing debounce listeners:
hotkeys.removeDebounce(key);