Tinykeys

A tiny (~400 B) & modern library for keybindings.

Keyboard
jamiebuilds/tinykeysjamiebuilds.github.io/tinykeys/tinykeys

README

tinykeys


A tiny (~400 B) & modern library for keybindings.

See Demo


Install


  1. ```sh
  2. npm install --save tinykeys
  3. ```

Or for a CDN version, you can use it on unpkg.com

Usage


  1. ``` js
  2. import tinykeys from "tinykeys" // Or `window.tinykeys` using the CDN version

  4. tinykeys(window, {
  5.   "Shift+D": () => {
  6.     alert("The 'Shift' and 'd' keys were pressed at the same time")
  7.   },
  8.   "y e e t": () => {
  9.     alert("The keys 'y', 'e', 'e', and 't' were pressed in order")
  10.   },
  11.   "$mod+KeyD": event => {
  12.     event.preventDefault()
  13.     alert("Either 'Control+d' or 'Meta+d' were pressed")
  14.   },
  15. })
  16. ```

Alternatively, if you want to only create the keybinding handler, and register
it as an event listener yourself:

  1. ``` js
  2. import { createKeybindingsHandler } from "tinykeys"

  4. let handler = createKeybindingsHandler({
  5.   "Shift+D": () => {
  6.     alert("The 'Shift' and 'd' keys were pressed at the same time")
  7.   },
  8.   "y e e t": () => {
  9.     alert("The keys 'y', 'e', 'e', and 't' were pressed in order")
  10.   },
  11.   "$mod+KeyD": event => {
  12.     event.preventDefault()
  13.     alert("Either 'Control+d' or 'Meta+d' were pressed")
  14.   },
  15. })

  17. window.addEventListener("keydown", handler)
  18. ```

React Hooks Example


If you're using tinykeys within a component, you should also make use of the
returned unsubscribe() function.

  1. ``` js
  2. import { useEffect } from "react"
  3. import tinykeys from "tinykeys"

  5. function useKeyboardShortcuts() {
  6.   useEffect(() => {
  7.     let unsubscribe = tinykeys(window, {
  8.       // ...
  9.     })
  10.     return () => {
  11.       unsubscribe()
  12.     }
  13.   })
  14. }
  15. ```

Commonly used key's and code's


Keybindings will be matched against
[KeyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key)
and[KeyboardEvent.code](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code/code_values)
which may have some names you don't expect.

WindowsmacOS`key``code`
-----------------------------------------------------------------------
N/A`Command``Meta``MetaLeft`
`Alt``Option``Alt``AltLeft`
`Control``Control``Control``ControlLeft`
`Shift``Shift``Shift``ShiftLeft`
`Space``Space`N/A`Space`
`Enter``Return``Enter``Enter`
`Esc``Esc``Escape``Escape`
`1`,`1`,`1`,`Digit1`,
`a`,`a`,`a`,`KeyA`,
`-``-``-``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](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code/code_values)
and
[KeyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key)
(case-insensitive).

  1. ``` js
  2. // Matches `event.key`:
  3. "d"
  4. // Matches: `event.code`:
  5. "KeyD"
  6. ```

Presses can optionally be prefixed with _modifiers_ which match against any
valid value to
[KeyboardEvent.getModifierState()](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/getModifierState).

  1. ``` js
  2. "Control+d"
  3. "Meta+d"
  4. "Shift+D"
  5. "Alt+KeyD"
  6. "Meta+Shift+D"
  7. ```

There is also a special $mod modifier that makes it easy to support cross
platform keybindings:

- Mac: $mod = Meta (⌘)
- Windows/Linux: $mod = Control

  1. ``` js
  2. "$mod+D" // Meta/Control+D
  3. "$mod+Shift+D" // Meta/Control+Shift+D
  4. ```

Keybinding Sequences


Keybindings can also consist of several key presses in a row:

  1. ``` js
  2. "g i" // i.e. "Go to Inbox"
  3. "g a" // i.e. "Go to Archive"
  4. "ArrowUp ArrowUp ArrowDown ArrowDown ArrowLeft ArrowRight ArrowLeft ArrowRight B A"
  5. ```

Each press can optionally be prefixed with modifier keys:

  1. ``` js
  2. "$mod+K $mod+1" // i.e. "Toggle Level 1"
  3. "$mod+K $mod+2" // i.e. "Toggle Level 2"
  4. "$mod+K $mod+3" // i.e. "Toggle Level 3"
  5. ```

Each press in the sequence must be pressed within 1000ms of the last.

Display the keyboard sequence


You can use the parseKeybinding method to get a structured representation of a
keyboard shortcut. It can be useful when you want to display it in a fancier way
than a plain string.

  1. ``` js
  2. import { parseKeybinding } from "tinykeys"

  4. let parsedShortcut = parseKeybinding("$mod+Shift+K $mod+1")
  5. ```

Results into:

  1. ``` js
  2. ;[
  3.   [["Meta", "Shift"], "K"],
  4.   [["Meta"], "1"],
  5. ]
  6. ```

Additional Configuration Options


You can configure the behavior of tinykeys in a couple ways using a third
options parameter.

  1. ``` js
  2. tinykey(
  3.   window,
  4.   {
  5.     M: toggleMute,
  6.   },
  7.   {
  8.     event: "keyup",
  9.   },
  10. )
  11. ```

options.event


Valid values: "keydown", "keyup"

Key presses will listen to this event (default: "keydown").

Note: Do not pass "keypress", it is deprecated in browsers.


options.timeout


Keybinding sequences will wait this long between key presses before cancelling
(default: 1000).

Note: Setting this value too low (i.e. 300) will be too fast for many of

your users.