tinykeys

On some non-US layouts (Windows/macOS), the AltGraph key may be reported. To ensure cross-platform compatibility, it is often safer to use event.code (e.g., KeyS) instead of event.key (e.g., S) when dealing with these modifiers.

tinykeys(window, {
  "Control+Alt+KeyS": event => {
    // macOS: `Control+Alt+S` or `Control+AltGraph+S`
    // Windows: `Control+Alt+S` or `Control+AltGraph+S` or `AltGraph+S`
  },
  "$mod+Alt+KeyS": event => {
    // macOS: `Meta+Alt+S` or `Meta+AltGraph+S`
    // Windows: `Control+Alt+S` or `Control+AltGraph+S` or `AltGraph+S`
  },
})

To use tinykeys in your project, install it using npm:

npm install --save tinykeys

Alternatively, you can use the CDN version via unpkg.com.

The third argument to tinykeys is an options object that allows you to customize behavior:

• event: The keyboard event to listen for. Valid values are "keydown" (default) and "keyup". Do not use "keypress".
• timeout: The time (in ms) to wait between key presses in a sequence before cancelling. Default is 1000.
• capture: Boolean to use event capturing.
• ignore: A filter function to determine which keyboard events should be ignored. By default, tinykeys ignores events from [contenteditable], input, textarea, and select unless they are the event.currentTarget.

tinykeys(
  window,
  {
    M: toggleMute,
  },
  {
    event: "keyup",
    capture: true,
  },
)

When using tinykeys inside a React component, ensure you return the unsubscribe() function from the useEffect hook to prevent memory leaks and unexpected behavior when the component unmounts.

import { useEffect } from "react"
import { tinykeys } from "tinykeys"

function useKeyboardShortcuts() {
  const formatBold = useEffectEvent(() => {
    // ...
  })

  const formatItalic = useEffectEvent(() => {
    // ...
  })

  useEffect(() => {
    return tinykeys(window, {
      "$mod+b": formatBold,
      "$mod+i": formatItalic,
    })
  }, [])
}

If you prefer to manage the event listener yourself, use createKeybindingsHandler. This returns a function that you can pass to addEventListener.

import { createKeybindingsHandler } from "tinykeys"

let handler = createKeybindingsHandler({
  "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")
  },
})

window.addEventListener("keydown", handler)

tinykeys matches against KeyboardEvent.key and KeyboardEvent.code. Use the following table for common mappings:

* Note: Some keys share the same code. International layouts may vary.

The defaultKeybindingsHandlerIgnore function is a predicate that returns true if a keyboard event should be ignored. By default, it ignores:

• Repeated events (event.repeat)
• Composition input (event.isComposing)
• Keyboard events targeting contenteditable elements, input, select, or textarea (unless the target is the currentTarget).

You can use this to extend the default ignoring logic.

tinykeys(window, {...}, {
  ignore: event => {
    return (
      // Also ignore events inside a dialog
      event.target.closest("dialog") != null &&
      defaultKeybindingsHandlerIgnore(event)
    );
  }
})

Use tinykeys to subscribe to keyboard events on a Window or HTMLElement. It accepts a map of keybinding strings to handler functions and returns an unsubscribe function to clean up the event listener.

Keybinding syntax supports:

• Single keys: "a"
• Modifiers: "Shift+d"
• Optional modifiers: "[Alt]+a"
• Sequences: "y e e t"
• Platform-agnostic modifier: "$mod+d" (maps to Control on Windows/Linux and Meta on macOS)
• Regex: "/(?:a|b)/"

import { tinykeys } from "tinykeys"

const unsubscribe = 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+d": () => {
		alert("Either 'Control+d' or 'Meta+d' were pressed")
	},
})

// Call unsubscribe() later to stop listening
// unsubscribe();