Stimulus cheatsheet

đź‘‹ FYI, this note is over 6 months old. Some of the content may be out of date.
On this page

Lifecycle callbacks Jump to heading

  • initialize: once, when the controller is first instantiated
  • connect: anytime the controller is connected to the DOM
  • disconnect: anytime the controller is disconnected from the DOM

Action descriptors Jump to heading

The data-action value click->hello#greet is called an action descriptor. This particular descriptor says:

  • click is the event name
  • hello is the controller identifier
  • greet is the name of the method to invoke

Common Events Have a Shorthand Action Notation Jump to heading

Stimulus defines click as the default event for actions on <button> elements. Certain other elements have default events, too. Here’s the full list:

Element > Default event Jump to heading

  • a > click
  • button > click
  • form > submit
  • input > change
  • input > type=submit click
  • select > change
  • textarea > change

Multiple Actions Jump to heading

If an element has muliple actions you can separate each one with a space click->hello#greet click->hello#save.

The element can even have multiple actions for multiple controllers click->hello#greet click->history#save.

Targets Jump to heading

The data-target value is called a target descriptor. This particular descriptor says:

  • hello is the controller identifier
  • name is the target name

When Stimulus loads your controller class, it looks for target name strings in a static array called targets. For each target name in the array, Stimulus adds three new properties to your controller. Here, our source target name becomes the following properties:

  • this.sourceTarget evaluates to the first source target in your controller’s scope. If there is no source target, accessing the property throws an error.
  • this.sourceTargets evaluates to an array of all source targets in the controller’s scope.
  • this.hasSourceTarget evaluates to true if there is a source target or false if not.

Multiple Targets Jump to heading

If an element is a target for multiple controllers you can separate each one with a space history.text

Naming Conventions Jump to heading

Component Convention Rationale
Controller filenames snake_case.js Rails works that way
Identifiers kebab-case Sometimes used as part of HTML attribute names; analogous to CSS classes, which are conventionally kebab-case
Action names camelCase Map directly to JavaScript controller methods
Target names camelCase Map directly to JavaScript controller properties
Data attributes camelCase + kebab-case Thin wrapper around the HTMLElement.dataSet API; camelCase names in JS, kebab-case attributes in HTML

Data API Jump to heading

Each Stimulus controller has a object with has(), get(), and set() methods. These methods provide convenient access to data attributes on the controller’s element, scoped by the controller’s identifier.

For example, in our controller above:

  •"index") returns true if the controller’s element has a data-slideshow-index attribute
  •"index") returns the string value of the element’s data-slideshow-index attribute
  •"index", index) sets the element’s data-slideshow-index attribute to the string value of index

If your attribute name consists of more than one word, reference it as camelCase in JavaScript and attribute-case in HTML. For example, you can read the data-slideshow-current-class-name attribute with"currentClassName").

HTML API Jump to heading

Controller data-controller Jump to heading

e.g. <div data-controller="ControllerName">

e.g. Multiple controllers on the same element: <div data-controller="ControllerName AnotherControllerName">

Target data-target Jump to heading

e.g. <input data-target="ControllerName.TargetName">

Action data-action Jump to heading

e.g. <button data-action="eventName->ControllerName#methodName">Click me</button>

e.g. Multiple actions on the same element: <button data-action="eventName->ControllerName#methodName anotherEventName->ControllerName#anotherMethodName">Click me</button>

Code snippets Jump to heading

Empty class Jump to heading

import { Controller } from 'stimulus'

export default class extends Controller {
static targets = []

// or
static get targets() {
return []

initialize() {}

connect() {}

disconnect() {}

HTML Jump to heading

Example HTML from the Stimulus home page

<div data-controller="hello">
<input data-target="" type="text" />

<button data-action="click->hello#greet">Greet</button>

<span data-target="hello.output"> </span>

← Back home