@luisliuchao/tinykeys
v1.1.1
Published
A tiny (~400 B) & modern library for keybindings.
Downloads
11
Maintainers
Readme
tinykeys
A tiny (~400 B) & modern library for keybindings. See Demo
Install
npm install --save tinykeys
Or for a CDN version, you can use it on unpkg.com
Usage
import tinykeys from "tinykeys" // Or `window.tinykeys` using the CDN version
tinykeys(window, {
"Shift+D": () => {
alert("The 'Shift' and 'd' keys were pressed at the same time")
},
"y e e t": () => {
alert("The keys 'y', 'e', 'e', and 't' were pressed in order")
},
"$mod+KeyD": event => {
event.preventDefault()
alert("Either 'Control+d' or 'Meta+d' were pressed")
},
})
React Hooks Example
If you're using tinykeys within a component, you should also make use of the
returned unsubscribe()
function.
import { useEffect } from "react"
import tinykeys from "tinykeys"
function useKeyboardShortcuts() {
useEffect(() => {
let unsubscribe = tinykeys(window, {
// ...
})
return () => {
unsubscribe()
}
})
}
Commonly used key
's and code
's
Keybindings will be matched against
KeyboardEvent.key
andKeyboardEvent.code
which may have some names you don't expect.
| Windows | macOS | key
| code
|
| ------------- | --------------- | ------------- | ------------------------------ |
| N/A | Command
/ ⌘
| Meta
| MetaLeft
/ MetaRight
|
| Alt
| Option
/ ⌥
| Alt
| AltLeft
/ AltRight
|
| Control
| Control
/ ^
| Control
| ControlLeft
/ ControlRight
|
| Shift
| Shift
| Shift
| ShiftLeft
/ ShiftRight
|
| Space
| Space
| N/A | Space
|
| Enter
| Return
| Enter
| Enter
|
| Esc
| Esc
| Escape
| Escape
|
| 1
, 2
, etc | 1
, 2
, etc | 1
, 2
, etc | Digit1
, Digit2
, etc |
| a
, b
, etc | a
, b
, etc | a
, b
, etc | KeyA
, KeyB
, etc |
| -
| -
| -
| Minus
|
| =
| =
| =
| Equal
|
| +
| +
| +
| Equal
* |
Something missing? Check out the key logger on the demo website
* Some keys will have the same code as others because they appear on the same key on the keyboard. Keep in mind how this is affected by international keyboards which may have different layouts.
Keybinding Syntax
Keybindings are made up of a sequence of presses.
A press can be as simple as a single key which matches against
KeyboardEvent.code
and
KeyboardEvent.key
(case-insensitive).
// Matches `event.key`:
"d"
// Matches: `event.code`:
"KeyD"
Presses can optionally be prefixed with modifiers which match against any
valid value to
KeyboardEvent.getModifierState()
.
"Control+d"
"Meta+d"
"Shift+D"
"Alt+KeyD"
"Meta+Shift+D"
There is also a special $mod
modifier that makes it easy to support cross
platform keybindings:
- Mac:
$mod
=Meta
(⌘) - Windows/Linux:
$mod
=Control
"$mod+D" // Meta/Control+D
"$mod+Shift+D" // Meta/Control+Shift+D
Keybinding Sequences
Keybindings can also consist of several key presses in a row:
"g i" // i.e. "Go to Inbox"
"g a" // i.e. "Go to Archive"
"ArrowUp ArrowUp ArrowDown ArrowDown ArrowLeft ArrowRight ArrowLeft ArrowRight B A"
Each press can optionally be prefixed with modifier keys:
"$mod+K $mod+1" // i.e. "Toggle Level 1"
"$mod+K $mod+2" // i.e. "Toggle Level 2"
"$mod+K $mod+3" // i.e. "Toggle Level 3"
Each press in the sequence must be pressed within 1000ms of the last.