Stimulus JavaScript Framework

An HTML element can belong to multiple controllers by including multiple target attributes. This allows different controllers to interact with the same element.

<form data-controller="search checkbox">
  <input type="checkbox" data-search-target="projects" data-checkbox-target="input">
  <input type="checkbox" data-search-target="messages" data-checkbox-target="input">
</form>

In this example:

• The search controller can access this.projectsTarget and this.messagesTarget.
• The checkbox controller can access this.inputTargets (an array containing both checkboxes).

Instead of hard-coding CSS class strings in your JavaScript, you can define CSS classes by a logical name using the static classes array in your controller. This allows you to map logical names to specific CSS classes via HTML data attributes, making your controllers more reusable and decoupled from specific styling implementations.

To define logical names, add a static classes array to your controller class containing the names in camelCase.

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

export default class extends Controller {
  static classes = [ "loading" ]

  // …
}

Scopes

When a controller connects to an element, that element and all its children constitute the controller's scope. The controller can only see targets and elements within this scope.

Nested Scopes

When controllers are nested, each controller is only aware of its own scope. It cannot see targets belonging to a nested controller.

For example, if a list controller contains a nested list controller, the parent controller's targets will not include the targets defined inside the child controller's scope.

When a controller manages external resources that are not part of the DOM (like setInterval timers or active HTTP requests), you must ensure they are properly cleaned up to prevent memory leaks or background processes running after the element is removed.

• Acquisition: Use the connect() lifecycle callback to start timers or initiate requests.
• Release: Use the disconnect() lifecycle callback to stop timers (e.g., via clearInterval) or cancel pending operations. This ensures the controller only consumes resources while it is actually connected to the DOM.

Stimulus follows a different paradigm than frameworks like React or Vue:

• HTML vs. JSON: While mainstream frameworks focus on turning JSON into DOM elements via template languages, Stimulus attaches itself to existing HTML (usually rendered by the server). Its primary goal is to manipulate existing elements rather than create them.
• State Management: In most frameworks, state is maintained in JavaScript objects and rendered to HTML. In Stimulus, state is stored in the HTML. This allows controllers to be discarded during page changes (like those performed by Turbo) and reinitialized correctly when the HTML is reloaded or cached.
• Complexity: Stimulus is designed to avoid the heavy lifting and indirection of complex client-side state management, favoring the simplicity of the request-response paradigm.

The connect() method is a lifecycle callback that Stimulus automatically calls every time a controller is connected to the document (i.e., when the element with the data-controller attribute enters the DOM). This is useful for initializing logic or logging connection status.

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    console.log("Controller connected!", this.element)
  }
}

Stimulus uses the DOM MutationObserver API to watch for changes. Consequently, lifecycle methods are called asynchronously in the next microtask following a document change.

Despite being asynchronous, methods follow a strict logical order:

• Two connect() calls will always be separated by a disconnect() call.
• Two [name]TargetConnected() calls for the same target will always be separated by a [name]TargetDisconnected() call for that same target.

Stimulus provides special methods called lifecycle callbacks that allow you to respond whenever a controller or its targets connect to or disconnect from the document. You can define these methods within your controller class to manage setup and teardown logic.

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    // Called when the controller is connected to the DOM
  }

  disconnect() {
    // Called when the controller is disconnected from the DOM
  }
}

Actions are the mechanism used to handle DOM events within Stimulus controllers. An action creates a connection between a DOM event listener, the controller's element, and a specific controller method.

An action descriptor follows the format: event->controller-identifier#method-name.

Example:

<div data-controller="gallery">
  <button data-action="click->gallery#next">…</button>
</div>

In the controller:

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  next(event) {
    // logic to execute
  }
}