Next to all-encompassing frameworks that grow to accommodate an ever larger set of concerns (e.g., client-side rendering, server-side rendering, routing, componentization, internationalization), Stimulus decidedly assumes a contained scope:
The documentation page provides the following example of HTML source:
<div data-controller="hello"> <input data-hello-target="name" type="text"> <button data-action="click->hello#greet"> Greet </button> <span data-hello-target="output"> </span> </div>
import Controller from "stimulus" export default class extends Controller static targets = [ "name", "output" ] greet() this.outputTarget.textContent = `Hello, $this.nameTarget.value!`
data-controller indicates to Stimulus that the corresponding DOM element will be handled by the
click->hello#greet) have Stimulus provisioning a
click event handler (
greet method of the
hello controller) on the corresponding DOM element. Stimulus additionally allows mapping important elements to controller properties. The controller having a reference to those elements may then update or inspect those elements according to the desired logic. The
data-hello-target attributes in the previous sample code thus reference a
output DOM elements available respectively as
this.outputTarget in the
There may, as a result, be less glue code to write. Stimulus may be viewed by some as a simpler alternative to fully-featured front-end framework with higher-level abstractions (e.g., virtual DOM, templating system, reactive values). While those frameworks, to a large extent, predicate separating application state from the DOM, sometimes even duplicating DOM state in custom data structures (virtual DOM), Stimulus rather relies on the DOM to hold pieces of application state, and encourages direct updates and inspection of DOM elements.
John Beatty, the author of tutorials for Stimulus, argued:
How many web pages actually need a JS framework?
Ruby on Rails creator David Heinemeier Hansson however emphasized that Stimulus does not fit every need:
Stimulus is concerned with manipulating this existing HTML document. […] There are cases where you’d want Stimulus to create new DOM elements, and you’re definitely free to do that. […] But it’s the minority use case. The focus is on manipulating, not creating elements.
Stimulus […] work great in conjunction with other, heavier approaches. If 80% of your application does not warrant the big rig, consider using our two-pack punch for that. Then roll out the heavy machinery for the part of your application that can really benefit from it. […]
Above all, it’s a toolkit for small teams who want to compete on fidelity and reach with much larger teams using more laborious, mainstream approaches.
GitHub quoted Stimulus as a source of inspiration for Catalyst, a set of patterns used at GitHub to make developing complex applications with web components easier. The three core Catalyst concepts (Observe, Listen, Query) adapt the three core Stimulus concepts (controllers, actions, and targets) to a context with custom elements.
Stimulus 2.0 builds on the previous version, fixes some bugs, and deprecates the data map API from Stimulus 1.0. Stimulus 2.0 additionally supports DOM event listener options and adds values and CSS classes APIs.
Stimulus is available under the MIT open source license and is available on GitHub.