Keymaster is a dependency-free library for defining and dispatching keyboard
shortcuts in web applications. It preserves the key(...) API and includes a
native custom element for displaying shortcuts.
This repository is a modernized fork of the original Keymaster, created by Thomas Fuchs. See the original project and this maintained fork.
For a browser script, include keymaster.js:
<script src="keymaster.js"></script>The package can also be loaded with CommonJS (require('keymaster')). It has no
runtime dependencies. Run npm test to execute the Node test suite.
Type declarations are included; no separate @types package is needed. With
esModuleInterop enabled, import and register shortcuts like this:
import key from 'keymaster';
key('ctrl+k', (event, shortcut) => {
console.log(shortcut.shortcut, shortcut.scope);
});Import the custom element module to register its tag and add its type to
document.createElement:
import 'keymaster/shortcut-element';
const shortcut = document.createElement('keymaster-shortcut');
shortcut.keys = 'ctrl+k';
shortcut.platform = 'auto';Import the custom element once through a package-aware bundler or import map.
It registers <keymaster-shortcut> automatically:
<script type="module">
import 'keymaster/shortcut-element';
</script>
<keymaster-shortcut keys="ctrl+k"></keymaster-shortcut>
<keymaster-shortcut keys="command+k, ctrl+k"></keymaster-shortcut>The keys attribute accepts the same modifier names and + chord syntax as
the keyboard library. Comma-separated shortcuts render as alternatives. The
platform attribute accepts auto (the default), mac, or another value to
choose platform-specific modifier labels.
The element uses an open shadow root. Style the key caps and separators with CSS custom properties or parts:
keymaster-shortcut {
--keymaster-key-background: #fff;
--keymaster-key-color: #20282d;
--keymaster-key-border: #8b969d;
--keymaster-key-radius: 3px;
}
keymaster-shortcut::part(key) {
padding: 0.2em 0.5em;
}One global method is exposed, key which defines shortcuts when
called directly.
// define short of 'a'
key('a', function(){ alert('you pressed a!') });
// returning false stops the event and prevents default browser events
key('ctrl+r', function(){ alert('stopped reload!'); return false });
// multiple shortcuts that do the same thing
key('⌘+r, ctrl+r', function(){ });The handler method is called with two arguments set, the keydown event fired, and
an object containing, among others, the following two properties:
shortcut: a string that contains the shortcut used, e.g. ctrl+r
scope: a string describing the scope (or all)
key('⌘+r, ctrl+r', function(event, handler){
console.log(handler.shortcut, handler.scope);
});
// "ctrl+r", "all"Keymaster understands the following modifiers:
⇧, shift, option, ⌥, alt, ctrl, control, command, and ⌘.
The following special keys can be used for shortcuts:
backspace, tab, clear, enter, return, esc, escape, space,
up, down, left, right, home, end, pageup, pagedown, del, delete
and f1 through f19.
At any point in time (even in code other than key shortcut handlers),
you can query the key object for the state of any keys. This
allows easy implementation of things like shift+click handlers. For example,
key.shift is true if the shift key is currently pressed.
if(key.shift) alert('shift is pressed, OMGZ!');At any point in time (even in code other than key shortcut handlers),
you can query the key object for the state of any key. This
is very helpful for game development using a game loop. For example,
key.isPressed(77) is true if the M key is currently pressed.
if(key.isPressed("M")) alert('M key is pressed, can ya believe it!?');
if(key.isPressed(77)) alert('M key is pressed, can ya believe it!?');You can also get these as an array using...
key.getPressedKeyCodes() // returns an array of key codes currently pressedIf you want to reuse the same shortcut for separate areas in your single page app,
Keymaster supports switching between scopes. Use the key.setScope method to set scope.
// define shortcuts with a scope
key('o, enter', 'issues', function(){ /* do something */ });
key('o, enter', 'files', function(){ /* do something else */ });
// set the scope (only 'all' and 'issues' shortcuts will be honored)
key.setScope('issues'); // default scope is 'all'
// remove all events that are set in 'issues' scope
key.deleteScope('issues');By default, Keymaster ignores shortcuts when an INPUT, SELECT, TEXTAREA,
or content-editable element is focused.
You can change this by overwriting key.filter with a new function. This function is called before
Keymaster processes shortcuts, with the keydown event as argument.
If your function returns false, then the no shortcuts will be processed.
Here's the default implementation for reference:
function filter(event) {
const target = event.target;
const tagName = target && target.tagName;
return !(tagName === 'INPUT' || tagName === 'SELECT' || tagName === 'TEXTAREA' ||
(target && target.isContentEditable));
}If you only want some shortcuts to work while in an input element, you can change the scope in the
key.filter function. Here's an example implementation, setting the scope to either 'input' or 'other'.
Don't forget to return true so the any shortcuts get processed.
key.filter = function(event) {
const target = event.target;
const tagName = target && target.tagName;
const isEditable = tagName === 'INPUT' || tagName === 'TEXTAREA' ||
tagName === 'SELECT' || (target && target.isContentEditable);
key.setScope(isEditable ? 'input' : 'other');
return true;
};However a more robust way to handle this is to use proper focus and blur event handlers on your input element, and change scopes there as you see fit.
You can call key.noConflict to remove the key function from global scope and restore whatever key was defined to before Keymaster was loaded. Calling key.noConflict will return the Keymaster key function.
var k = key.noConflict();
k('a', function() { /* ... */ });
key()
// --> TypeError: 'undefined' is not a functionSimilar to defining shortcuts, they can be unbound using key.unbind.
// unbind 'a' handler
key.unbind('a');
// unbind a key only for a single scope
// when no scope is specified it defaults to the current scope (key.getScope())
key.unbind('o, enter', 'issues');
key.unbind('o, enter', 'files');The browser entry uses KeyboardEvent.code when available and falls back to
legacy key codes. Shortcuts are ignored in input, select, textarea, and
content-editable elements by default. Override key.filter to change this.
The index.html file is the publishable interactive demo. Serve the repository
root over HTTP to try it locally.
Run npm test before submitting a change. The browser demo is in index.html.
Keymaster may be freely distributed under the MIT license. See MIT-LICENSE.