A new version of Stimulus is out. Here are some things to consider if you decide to update to 2.0. It adds a Values api, CSS classes, and a change to the target attribute syntax.

Upgrading Stimulus

First, update Stimulus with Yarn.

$ yarn add stimulus

This will update the library itself, and all the dependencies.

Look for data-target Warnings

Stimulus 2.0 is backwards compatible with Stimulus 1. It will drop a warning in your development console to help you find the changes you need to make.

One big change is the addition the controller name to the data attribute for targets.

data-target="hello.output" becomes data-hello-target="output" and data-target="meta-state.output" becomes data-meta-state-target="output".

This should help with code readability and when you search for the attributes.

CSS Classes

One new feature of Stimulus 2.0 is CSS Classes. In the Todo Filter tutorial, it uses class to hide data. The first thing is to add the class to the HTML.

The tag <div data-controller="filter"> becomes <div data-controller="filter" data-filter-not-found-class="filter--notFound">. The data-filter refers to the controller, the not-found is the class name that will be set in the controller, and the class denotes this is a CSS class.

The Stimulus controller gets a new static addition:

static classes = ["notFound"];

Note the not-found in the HTML part becomes a camelCase "notFound". Now anywhere you need to use the class in the html, simply call this.notFoundClass.

Data Mapping

The second big new feature of Stimulus 2.0 is Value Mapping. This builds on the previous way of adding data attributes to a controller. The new way lets you specify the type of those values, so what is really a number or a boolean doesn’t need to be coerced manually from a string. You can upgrade your data types easily by adding -value to an existing data value. For example, <div data-controller="meta-state" data-meta-state-key="account-id"> becomes <div data-controller="meta-state" data-meta-state-key-value="account-id">. You need to set the types in the controller like this:

static values = { key: String };

And then, instead of getting the key like:

this.accountID = getMetaValue(this.data.get("key"));

access the key with the new syntax:

this.accountID = getMetaValue(this.keyValue);

What does this mean?

These changes help decouple the Stimulus controllers even more from the HTML, while adding the ability to set values as a designer. Your controllers are now more reusable in different contexts, such as as the reordering Todos example. I think these help developers save time, and make more interactive web applications.

Comments or Questions? Let me know how your experience went below.

Want To Learn More?

Try out some more of my Stimulus.js Tutorials.