Null Pointer Micromanagement
    Wondering what’s next for npm?Check out our public roadmap! »

    tinykeys
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.2 • Public • Published

    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.

    Install

    npm i tinykeys

    DownloadsWeekly Downloads

    3,679

    Version

    1.1.2

    License

    MIT

    Unpacked Size

    38.5 kB

    Total Files

    12

    Last publish

    Collaborators

    • avatar