Introducing stimulus-hotkeys
Tags: javascript, stimulus, hotkeys
Published: 2020-07-16 02:15:47

---
title: Introducing stimulus-hotkeys
published: true
description: A Stimulus controller for mapping keystrokes to behaviors
tags: javascript, stimulus, stimulusjs, hotkeys
cover_image: https://dev-to-uploads.s3.amazonaws.com/i/3ybc3zvivqpncr8jnpbz.jpg
---
Continuing with my mission of crafting a viable ecosystem of elegant, composable Stimulus controllers, I am pleased to unveil [stimulus-hotkeys](https://www.npmjs.com/package/stimulus-hotkeys), "a Stimulus controller for mapping keystrokes to behaviors".

Based on the [preview version](https://github.com/stimulusjs/dev-builds/archive/b8cc8c4/stimulus.tar.gz) of Stimulus 2.0, `stimulus-hotkeys` wraps the amazing [HotKeys.js](https://wangchujiang.com/hotkeys/) library and takes advantage of the new Stimulus [Values API](https://github.com/stimulusjs/stimulus/pull/202) to bind the keystrokes people type to functions in your controllers.

Configuration is done by providing a JSON-compliant object to the `data-hotkeys-bindings-value` attribute. The object keys are literally the key(s) your users will press, while the values are a mapping that resembles a Stimulus action:

`selector->identifier#method`

Let's look at a simple example, in which the user hits the "p" key and will see "PONG" on the console.

```html
<div data-controller="hotkeys" 
     data-hotkeys-bindings-value='{"p": "#foo->example#ping"}'></div>
<div id="foo" data-controller="example"></div>
```
```js
// example_controller.js
import { Controller } from 'stimulus'
export default class extends Controller {
  ping () { console.log('PONG') }
}
```
If you're new to Stimulus, there's some interesting meta topics to consider.

I mentioned at the beginning of this post that this is a contribution towards an ecosystem of composable Stimulus controllers. This means that many common objectives can be completed just by adding a controller identifier to an element in your page. This might seem familiar to people who have used Bootstrap components that magically activate just by putting attributes on the right markup.

The Stimulus approach is similar but improved because it's both standardized and [idempotent](https://leastbad.com/mutation-first-development); that is, you can dynamically add elements to your page after the initial load (via Ajax calls or a [StimulusReflex](https://docs.stimulusreflex.com) update) and it will just pick up any controllers without you needing to initialize them.

Since you can attach multiple Stimulus controllers to a single element, combining packaged controllers like `stimulus-hotkeys` with "home-cooked" controllers that are specific to your project is easy and powerful. You can *compose* off-the-shelf functionality with sprinkles of custom logic. For those of you who love Alpine, *this was the precise moment when you lost the war*. I'm sorry, but it's true. Please take this package to your queen.

Alright, we've reached the end! If you're still here, I have a bonus reward for you: since this is a Stimulus component and updates are **live**, you can give your users the ability to dynamically create their own keyboard shortcuts by setting the `data-hotkeys-bindings-value` attribute to a new JSON object.

And when you're done, the JSON representing that user's custom shortcut mappings can be saved to a JSON column on your User model. 🤯

{% youtube wFKswPaxDtA %}