A modern and powerful shortcuts management library.
- It is largely built on top of
KeyboardEvent#code
, for great compatibility across browsers, platforms, languages and layouts. - It is fast. Almost always this library will do
O(1)
registrations,O(1)
disposals,O(1)
lookups andO(1)
resetting. - It supports ~100 keyboard keys, including function keys and numpad keys.
- It supports mouse buttons too, which can be mixed in shortcts with keyboard keys, like
Ctrl+ClickLeft
. - It supports simple shortcuts, like
Ctrl+F
, and shortcuts sequences, likeCtrl+K Ctrl+F
. - It supports detecting which exact modifier key was pressed, like
ControlLeft
orControlRight
. - It supports common aliases for keys, like
Alt
/Option
, orEsc
/Escape
. - It supports some character-based shortcuts, like
Shift+#
, rather than the equivalent key-based shortcut, which might beShift+3
. - It supports automatically using
Command
under macOS andControl
elsewhere, by writing for exampleCommandOrControl+F
. - It supports Konami code, a.k.a. cheatcode shortcuts, like
Up Up Down Down Left Right Left Right B A
.
The following keys can be used when defining a shortcut:
- Modifiers: Alt/Option, Cmd/Command/Meta, Ctrl/Control, Shift, CmdOrCtrl/CommandOrControl.
- Left modifiers: AltLeft/OptionLeft, CmdLeft/CommandLeft/MetaLeft, CtrlLeft/ControLeft, CmdLeftOrCtrlLeft/CommandLeftOrControlLeft.
- Right modifiers: AltRight/OptionRight, CmdRight/CommandRight/MetaRight, CtrlRight/ControRight, CmdRightOrCtrlRight/CommandRightOrControlRight.
- Digits: 0-9.
- Alphabet letters: A-Z.
- Function keys: F1-F24.
- Numpad digits: Numpad0-Numpad9.
- Numpad operators: NumpadAdd, NumpadComma, NumpadDecimal, NumpadDivide, NumpadEnter, NumpadEqual, NumpadMultiply, NumpadSubtract.
- Special keys: Backspace, Capslock, Del/Delete, Down, End, Enter/Return, Esc/Escape, Home, Insert, Left, PageDown, PageUp, Right, Space/Spacebar, Tab, Up, NumLock, ScrollLock.
- Punctuation keys: !, @, #, $, %, ^, &, *, ( , ), _, {, }, |, :, ", <, >, ?, ~.
- Mouse buttons: ClickLeft/MouseLeft, ClickMiddle/MouseMiddle, ClickRight/MouseRight, Mouse0-Mouse9.
Please note that:
- ℹ️ Other keys are not supported.
- ℹ️ Shortcuts are case insensitive.
- ℹ️ Keys in a single shortcut must be joined by a plus sign (e.g. Ctrl+A).
- ℹ️ Sequences of shortcuts must be joined by a space (e.g. Ctrl+K Ctrl+B).
⚠️ Punctuation keys should be avoided when possible, as they are currently supported in a way that can use differences between layouts.
npm install --save shosho
import ShoSho from 'shosho';
// Let's create a shortcuts manager
const shortcuts = new ShoSho ({
capture: true,
target: document,
shouldHandleEvent ( event ) {
// Return "true" if this event should be handled
return true;
}
});
// Let's register some shortcuts. Shortcuts handlers must return "true" if they actually handled the shortcut
shortcuts.register ( 'A', event => { // Single-key shortcut
console.log ( 'Handling A' );
return true;
});
shortcuts.register ( 'Ctrl+F', event => { // Simple modifier+trigger shortcut
console.log ( 'Handling Ctrl+F' );
return true;
});
shortcuts.register ( 'Ctrl+K Ctrl+F', event => { // Advanced sequence shortcut
console.log ( 'Handling CtrlK Ctrl+F' );
return true;
});
shortcuts.register ( 'ClickMiddle', event => { // Single-mouse-button shortcut
console.log ( 'Skipping ClickMiddle actually' );
return false; // Returning "false" tells the library to try other potential handlers for this shortcut
});
shortcuts.register ( 'CmdOrCtrl+ClickRight', event => { // Advanced mixed keyboard/mouse shortcut
console.log ( 'Handling CmdOrCtrl+ClickRight' );
return true;
});
// Let's register a Konami code, which basically is not affected by other registered shortcuts
shortcuts.register ( 'Up Up Down Down Left Right Left Right B A', event => { // A Konami code
console.log ( 'Secret shortcut truggered 🚀' );
}, { konami: true } ); // Registering it as a Konami code
// Let's register a shortcut but then dispose of it
const dispose = shortcuts.register ( 'Shift+1', event => {
console.log ( 'Handling Shift+1' );
return true;
});
dispose (); // Unregistering that shortcut with that handler
// Let's trigger a shortcut programmatically, perhaps for debugging purposes
const handled = shortcuts.trigger ( 'Ctrl+F' );
console.log ( handled ); // => true
// Let's actually start listening for shortcuts
shortcuts.start ();
// Let's stop listening for shortcuts
shortcuts.stop ();
// Let's dispose of all registered shortcuts
shortcuts.reset ();
MIT © Fabio Spampinato