hotkey-listener

A modest js library that dispatches low-level keyboard events in the form of CustomEvents.

Foreword

Hotkey listener is 5.99kb according to Unpkg. https://unpkg.com/browse/hotkey-listener/

Hotkey Listener is 2.6kb GZipped according to Bundlephobia. https://bundlephobia.com/[email protected]

Hotkey Listener can only be registered on HTMLElement's that implement the "KeyboardEvent" interface.

For example: window, document

Installation

npm install hotkey-listener

## OR

yarn add hotkey-listener

Usage

// index.js
import hotkeyListener from "hotkey-listener"

hotkeyListener.register({
  element: window,
  keys: [
    "f5",
    "ctrl+d"
  ],
  eventOptions: {
    // Required to preventDefault() in chrome
    cancelable: true
  }
})

window.addEventListener("keydown:f5", (event) => {
  // Prevent window refresh
  event.preventDefault()
  console.log("f5 pushed")
  console.log(event.cancelable)
})

window.addEventListener("keydown:ctrl+d", (event) => {
  event.preventDefault()
  console.log(`${event.detail.key} pushed`) // ctrl+d pressed
})

Hotkey listener creates custom keyup:<keystroke> and keydown:<keystroke> events.

Events also record the key that was pressed via event.detail.key

API Reference

hotkeyListener.register({
  element: <HTMLElement>, // Default is window
  keys: <String[]>,

  // https://github.com/jaywcjlove/hotkeys#option
  // element, keyup, and keydown are already predefined
  hotkeyOptions: {
    scope: <String>,
    splitKey <String>
  },

  // https://developer.mozilla.org/en-US/docs/Web/API/Event/Event
  // https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent
  eventOptions: {
    bubbles: <Boolean>, // default false
    cancelable: <Boolean>, // default false
    composed: <Boolean>, // default false
    detail: { key: "<key pressed>" }
    // Detail is an Object you can attach other [key: value] pairs to
  },
})

Hotkeys API

Should you need more finely grained tuning of hotkeys, you can communicate with the hotkeys API directly. For example, to enable hotkeys on input, textarea, etc, you can do the following:

import hotkeyListener from "hotkey-listener"

hotkeyListener.hotkeys.filter = function(event) {
  return true
}

Usage with Stimulus

// application.js
import hotkeyListener from "hotkey-listener"

hotkeyListener.register({
  element: window,
  keys: [
    "f5",
    "ctrl+d"
  ],
  eventOptions: {
    // Required to preventDefault() in chrome
    cancelable: true
  }
})

Then in your HTML for a stimulus controller you can do this:

<div data-action="keydown:f5@window->my-controller#doStuff">
</div>

https://github.com/jaywcjlove/hotkeys#filter

How it works?

Hotkey-Listener under the hood uses the hotkeys library to dispatch CustomEvents to the client.

Contributors