useHotkeys

The useHotkeys behavior can be used to register hotkeys using the hotkeys-js library. To use it, do the following:

1. Install the hotkeys-js peer dependency:

yarn add hotkeys-js

bin/importmap pin stimulus-use/hotkeys
bin/importmap pin hotkeys-js

2. Define hotkeys and respective handlers and pass them as an argument to useHotkeys.

Importing the behavior

Note

stimulus-use version 0.52.0 changed the way how this behavior needs to be imported in your application.

- import { useHotkeys } from "stimulus-use"
+ import { useHotkeys } from "stimulus-use/hotkeys"

Also, please add hotkeys-js as a npm dependency to your application if you haven't added it yet, version 0.52.0 removed it as a dependency.

Reference

useHotkeys(controller, options)

controller : a Stimulus Controller (usually 'this')

options : Hotkey definitions, in simple or advanced format (see examples below)

simple:

{ [hotkey: string]: [handler: KeyHandler, element: HTMLElement] }

advanced:

{
  hotkeys?: {
    [hotkey: string]: {
      handler: Keyhandler
      options: {
        scope?: string
        element?: HTMLElement
        keyup?: boolean
        keydown?: boolean
        splitKey?: string
      }
    }
  }
  filter?: (e: KeyboardEvent) => boolean
  debug?: boolean
}

The advanced format also accepts the inherited debug option. Set it to true to log debug information. See debug for more information on the debugging tools (defaults to false).

Re-binding and unbinding hotkeys

useHotkeys() returns an object exposing bind and unbind methods, which you can use to register or remove the configured hotkeys at runtime. The hotkeys are automatically unbound when the controller disconnects.

import { Controller } from '@hotwired/stimulus'
import { useHotkeys } from 'stimulus-use/hotkeys'

export default class extends Controller {
  connect() {
    this.hotkeys = useHotkeys(this, {
      '/': [this.singleKeyHandler]
    })
  }

  disableHotkeys() {
    this.hotkeys.unbind()
  }

  enableHotkeys() {
    this.hotkeys.bind()
  }
}

Usage

Simple Hotkey Definition

import { Controller } from '@hotwired/stimulus'
import { useHotkeys } from 'stimulus-use/hotkeys'

export default class extends Controller {
  connect() {
    useHotkeys(this, {
      '/': [this.singleKeyHandler],
      'cmd+a': [this.metaKeyHandler],
      b: [this.inputHandler],
      e: [this.inputHandler, this.inputTarget]
    })
  }
}

Advanced Hotkey Definition

import { Controller } from '@hotwired/stimulus'
import { useHotkeys } from 'stimulus-use/hotkeys'

export default class extends Controller {
  connect() {
    useHotkeys(this, {
      hotkeys: {
        '/': {
          handler: this.singleKeyHandler
        },
        'cmd+a': {
          handler: this.metaKeyHandler
        },
        f: {
          handler: this.scopeHandler,
          options: {
            scope: 'files'
          }
        },
        b: {
          handler: this.inputHandler
        },
        c: {
          handler: this.keyUpHandler,
          options: {
            keydown: false,
            keyup: true
          }
        },
        'ctrl-d': {
          handler: this.splitKeyHandler,
          options: {
            splitKey: '-'
          }
        }
      },
      filter: this.filter
    })
  }

  singleKeyHandler(e) {
    // ...
  }
}