Introducing stimulus-hotkeys

Continuing with my mission of crafting a viable ecosystem of elegant, composable Stimulus controllers, I am pleases to unveil stimulus-hotkeys, “a Stimulus controller for mapping keystrokes to behaviors”.

Based on the preview version of Stimulus 2.0, stimulus-hotkeys wraps the amazing HotKeys.js library and takes advantage of the new Stimulus Values API 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.

<div data-controller="hotkeys" 
     data-hotkeys-bindings-value='{"p": "#foo->example#ping"}'></div>
<div id="foo" data-controller="example"></div>

// 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; that is, you can dynamically add elements to your page after the initial load (via Ajax calls or a StimulusReflex 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. 🤯