Guide · Open source

How to use Stimulus: attributes, controllers and actions

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Stimulus is a JavaScript framework that adds interactive behavior to HTML you already render on the server. You mark elements with data attributes, then write a small controller class that responds to them. This guide walks through the attributes, a working controller example, install options and the cases where Stimulus is a good fit.

Stimulushotwired/stimulus · ★ 13.1k · MIT Install options & downloads

Quick start

1Read the Handbook intro. Start with the Stimulus Handbook to see the core idea and build a first controller.
2Add a controller attribute. Put data-controller on a container element, using the name you will give your controller.
3Mark targets. Add data-NAME-target attributes to the elements your code needs to read or update.
4Connect an action. Use data-action with the form event->controller#method to call a method on a DOM event.
5Write the controller class. Create a file named after the controller, import Controller from @hotwired/stimulus and define the methods.
6Load the script. Add Stimulus through your asset packaging system or a script tag, following the Installation Guide.

What Stimulus does and does not do

Stimulus is built to augment your HTML with just enough behavior. It is not concerned with rendering HTML at all, so it does not generate your page markup. Your server or template system still produces the HTML, and Stimulus adds behavior on top of it.

Stimulus pairs with Turbo, which the README describes as a way to build fast applications with minimal effort.

Good fit: server-rendered apps that need light interactivity
Not a fit: client-side rendered single-page apps, since Stimulus does not render HTML

Mark your HTML with controller, target and action attributes

Start by adding a controller attribute to an element. Targets are named elements inside that controller that your code can reference. Actions connect a DOM event, such as a click, to a method on the controller.

In the example from the README, the data-action value click->hello#greet means: on click, call the greet method of the hello controller.

data-controller names the controller, here hello
data-hello-target marks elements the controller can reference by name
data-action uses the form event->controller#method

<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>

Write a controller class

Create a controller file that matches the name in data-controller. The README example is named hello_controller.js. It imports Controller from @hotwired/stimulus, lists its targets in a static array, and defines methods that actions can call.

Inside the methods, the README uses this.nameTarget and this.outputTarget to read and write the elements marked in the HTML.

Import Controller from "@hotwired/stimulus"
Declare targets with static targets = [ "name", "output" ]
Call methods from data-action attributes

// hello_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = [ "name", "output" ]

  greet() {
    this.outputTarget.textContent =
      `Hello, ${this.nameTarget.value}!`
  }
}

Understand how Stimulus keeps up with page changes

Stimulus watches the page continuously. It starts a controller when its attributes appear and cleans up when they disappear. The README says this works for a full page load, a Turbo page change, or an Ajax request, so you do not need separate wiring for each case.

The Stimulus Handbook walks through building a first controller and is the recommended next read.

Install Stimulus or use a script tag

Stimulus works with any asset packaging system. If you prefer no build step, the README says you can drop a script tag on the page instead. For detailed instructions, follow the Installation Guide in the Stimulus Handbook.

If you work on the Stimulus source itself, the README's development setup uses Yarn and Node.js. Install dependencies with yarn install.

Package manager: use it with any asset packaging system
No build step: add a script tag to the page
Contributors: run yarn install, then yarn start, yarn test, yarn lint or yarn format

yarn install

Where to find help

The Stimulus Reference lists API details once you have read the Handbook. For questions, the README points to the Hotwire Discourse community forum. Bugs go to the GitHub issue tracker.

Handbook: https://stimulus.hotwired.dev/handbook/introduction
Reference: https://stimulus.hotwired.dev/reference/controllers
Forum: https://discuss.hotwired.dev/

What people use it for

Greeting or live-output forms, as in the README hello example, where input updates a span
Adding interactive behavior to server-rendered pages that already use Turbo
Attaching small click or input behaviors to existing HTML without a full front-end framework

Frequently asked questions

Is Stimulus free to use?

Yes. The repository is MIT-licensed, which the README states, and it was released by Basecamp. You can use it in commercial projects under that licence; check the LICENSE file for the full terms.

Do I need a build step to use Stimulus?

No. The README says you can use Stimulus with any asset packaging system, or skip the build step entirely by dropping a script tag on the page.

What do I need installed before using Stimulus?

The README assumes you already know HTML and JavaScript. For the Yarn-based development workflow it mentions, you need Node.js and then run yarn install.

Is Stimulus a replacement for React or Vue?

Not for the same job. Stimulus does not render HTML, so it suits server-rendered pages that need light interactivity. The README says it is not for teams building full client-side rendered single-page apps.

How does Stimulus compare to Alpine.js or htmx?

The README does not compare them. Alpine.js, htmx and Hotwire Turbo are listed as comparable projects, so evaluate each against your needs, such as whether you already use Turbo or prefer attributes on HTML.

Where do I get help if my controller does not work?

Start with the Stimulus Reference for API details. For questions, the README points to the Hotwire Discourse forum, and for bugs you can open an issue on the GitHub issue tracker.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use Stimulus if you render HTML on the server and want small, well-scoped interactivity, especially alongside Turbo. Pick a different tool if you are building a full client-side rendered single-page app or if you are new to HTML and JavaScript and need more guidance first.

Install options & downloads