Stimulus controllers

A Kaksha fee form should show the total for ten seats, 17,700,000 minor units of the institute’s currency, the moment someone types 10 in the seats field, without asking the server. A Stimulus controllerStimulus controller: A JavaScript class that Stimulus attaches to any element carrying data-controller with the controller's identifier, giving the element behaviour through actions, targets and values. is a small JavaScript class that Stimulus attaches to any element carrying data-controller; you write one when the behaviour belongs in the browser and needs no server request, such as a live total, a character counter, a copy button or an aria-expanded toggle.

A new Rails 8.1 app includes Stimulus beside Turbo: Turbo keeps rendering pages on the server, and a controller adds only what the server cannot. This lesson takes a controller apart, shows what connect() and disconnect() do when Turbo swaps elements, and gives a rule for choosing Stimulus or Turbo alone.

A controller connects JavaScript to HTML with data attributes

Stimulus does one thing: it finds elements marked with data-controller and attaches a JavaScript object to each. The value of the attribute names the controller, and Stimulus creates an instance of the matching class and keeps it alive as long as the element stays in the page. The Stimulus Handbook calls this a bridge from HTML to JavaScript, the way the class attribute bridges HTML to CSS.

A new Rails 8.1.4 app has Stimulus wired up already. The generated import mapimport map: A JSON object in a script tag of type importmap that tells the browser which file each JavaScript module name stands for, so modules can import each other by name without a bundler. More in “Assets: Propshaft, import maps and CSS” in config/importmap.rb pins the controllers folder with pin_all_from "app/javascript/controllers", under: "controllers", and app/javascript/controllers/application.js starts the Stimulus application. The generated app/javascript/controllers/hello_controller.js shows the shape:

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    this.element.textContent = "Hello World!"
  }
}

The class extends Controller, defines a connect method and uses this.element to reach the DOM element that carries data-controller="hello". The method sets the element’s text to “Hello World!”, so any page that includes <div data-controller="hello"></div> shows that greeting as soon as the element appears.

The file name decides the identifier. Underscores in the name become dashes, so fee_calculator_controller.js answers to data-controller="fee-calculator", and a slash for a subfolder becomes two dashes, so users/profile_controller.js answers to users--profile. The Stimulus generator writes the identifier into the comment at the top of each file it creates:

# The Stimulus generator writes the identifier for you: generate one controller at the
# top level and one in a subfolder, then read the comment at the top of the new file.
require_relative "session"

Session.run(<<~SH)
  cd ../kaksha
  bin/rails generate stimulus character_counter
  bin/rails generate stimulus users/profile
  grep -n 'Connects to' app/javascript/controllers/character_counter_controller.js
  cat app/javascript/controllers/users/profile_controller.js
SH

$ cd ../kaksha
$ bin/rails generate stimulus character_counter
      create  app/javascript/controllers/character_counter_controller.js
$ bin/rails generate stimulus users/profile
      create  app/javascript/controllers/users/profile_controller.js
$ grep -n 'Connects to' app/javascript/controllers/character_counter_controller.js
3:// Connects to data-controller="character-counter"
$ cat app/javascript/controllers/users/profile_controller.js
import { Controller } from "@hotwired/stimulus"

// Connects to data-controller="users--profile"
export default class extends Controller {
  connect() {
  }
}

Actions, targets and values give a controller its parts

A controller needs three more ideas to do real work:

1. Actions connect DOM events to controller methods. An element with data-action="click->fee-calculator#calculate" calls the controller’s calculate method when clicked. The pattern is event->controller#method, and Stimulus wires the listener for you.

2. Targets name elements the controller works with. Declare them at the top of the class with static targets = ["total"], and Stimulus creates this.totalTarget (the first match), this.totalTargets (all matches) and this.hasTotalTarget (a boolean). Mark an element with data-fee-calculator-target="total", and your method can read or write it without querySelector. Reading this.totalTarget when no element matches throws an error, so test hasTotalTarget first for a target that may be missing.

3. Values hold typed data on the controller’s element. Declare them with static values = { rate: Number, currency: String }, and Stimulus reads data-fee-calculator-rate-value="18" into this.rateValue as the number 18. Change this.rateValue and the attribute updates; define rateValueChanged() and Stimulus calls it whenever the value changes.

Together they keep the controller short. The HTML declares which elements matter and what events trigger which actions; the JavaScript does the work.

The fee calculator below shows all three, one file at a time. First the HTML the server sends: four values carry the fee per seat (1500000 minor units, so 15,000.00 once a locale and a currency format it), the tax rate, a locale and a currency; two targets mark the quantity field and the total; one action runs the calculation on every input event. The form submits to the server as it stands, and the amount already in its output element is the 1770000 minor units that the run below prints for one seat.

<!-- The fee form as the server sends it. It submits and shows a total with no JavaScript;
     the controller only makes the total follow the field while someone types. -->
<form action="/fees/quote" method="post"
      data-controller="fee-calculator"
      data-fee-calculator-base-value="1500000"
      data-fee-calculator-rate-value="18"
      data-fee-calculator-locale-value="en-IN"
      data-fee-calculator-currency-value="INR">
  <label for="quantity">Seats</label>
  <input id="quantity" name="quantity" type="number" min="1" value="1"
         data-fee-calculator-target="quantity"
         data-action="input->fee-calculator#calculate">
  <p>Total: <output data-fee-calculator-target="total">₹17,700.00</output></p>
  <button type="submit">Get a quote</button>
</form>

Next the arithmetic, run as plain JavaScript so you can see what it prints for one, two and ten seats and for three locales:

// The fee arithmetic of the Stimulus controller, run on its own. Amounts are whole
// minor units (cents, paise), so the sums stay exact; Intl.NumberFormat turns the
// result into text for a locale and a currency, the two String values of the controller.

function calculateTotal(baseMinor, quantity, taxRatePercent) {
  const subtotal = baseMinor * quantity;
  const tax = Math.round((subtotal * taxRatePercent) / 100);
  return subtotal + tax;
}

function formatAmount(minorUnits, locale, currency) {
  return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(minorUnits / 100);
}

const base = 1500000; // the fee per seat: 15,000.00 in minor units
const taxRate = 18; // per cent

for (const quantity of [1, 2, 10]) {
  console.log(`quantity ${quantity}: total ${calculateTotal(base, quantity, taxRate)} minor units`);
}

const total = calculateTotal(base, 10, taxRate);
for (const [locale, currency] of [['en-US', 'USD'], ['de-DE', 'EUR'], ['en-IN', 'INR']]) {
  console.log(`${locale} ${currency}: ${formatAmount(total, locale, currency)}`);
}

quantity 1: total 1770000 minor units
quantity 2: total 3540000 minor units
quantity 10: total 17700000 minor units
en-US USD: $177,000.00
de-DE EUR: 177.000,00 €
en-IN INR: ₹1,77,000.00

Last the Stimulus controller, which holds the same arithmetic and only displays its result:

// app/javascript/controllers/fee_calculator_controller.js
// Values carry the numbers, targets mark the quantity field and the total, and an
// action on the field (input->fee-calculator#calculate) runs calculate() on every input.
import { Controller } from "@hotwired/stimulus"

// Connects to data-controller="fee-calculator"
export default class extends Controller {
  static targets = ["quantity", "total"]
  static values = {
    base: Number,                               // fee per seat in minor units (cents, paise)
    rate: Number,                               // tax rate in per cent, e.g. 18
    locale: { type: String, default: "en-US" },
    currency: { type: String, default: "USD" }
  }

  connect() {
    this.calculate() // show a total as soon as the form appears
  }

  calculate() {
    const quantity = parseInt(this.quantityTarget.value, 10) || 0
    const subtotal = this.baseValue * quantity
    const total = subtotal + Math.round((subtotal * this.rateValue) / 100)
    this.totalTarget.textContent = new Intl.NumberFormat(this.localeValue, {
      style: "currency",
      currency: this.currencyValue
    }).format(total / 100)
  }
}

Classes and outlets reach beyond the controller’s own element

Two more declarations round out Stimulus:

Classes let the HTML name CSS classes the controller should use. Declare them with static classes = ["active"], mark the element with data-fee-calculator-active-class="bg-green-100", and your code reads this.activeClass to get that string. The controller never hard-codes a class name, so the same JavaScript works with any design system.

Outlets connect one controller to another. Declare them with static outlets = ["chart"] and mark which element to connect with data-fee-calculator-chart-outlet="#totals-chart". The element that selector finds must itself carry data-controller="chart", because an outlet’s name is the other controller’s identifier. Now this.chartOutlet returns the chart controller instance, and you can call its methods directly; it throws when no such element exists, so check this.hasChartOutlet first when the chart may be absent. Outlets are an alternative to dispatching custom events between controllers.

Both keep the controller generic: the HTML tells it which classes to toggle and which other controllers to talk to.

Turbo swaps the element, so Stimulus runs disconnect, then connect

When Turbo Drive or a Turbo Frame replaces part of the page, Stimulus notices through the browser’s MutationObserver and reacts in the next microtask. The old element has left the document, so Stimulus calls disconnect() on its controller. The new element carries data-controller, so Stimulus creates a controller for it and calls connect(). One swap is one disconnect() followed by one connect(); Stimulus never rebuilds the page from scratch, and it cleans up nothing that your code set up outside the element. That is why code that works on first load still works after Turbo navigation.

The lifecycle has three callbacks:

Two connect() calls on one instance are always separated by one disconnect(). When a swap brings in a new element, the controller is a new instance and initialize() runs again. When Stimulus sees the same element removed and attached again, it reuses the old instance: connect() runs a second time and initialize() does not.

The most common mistake is forgetting that cleanup. A listener on a global object such as window or document does not disappear with the element:

Progressive enhancement: the page should work without JavaScript

Stimulus is designed for progressive enhancementprogressive enhancement: Building a page that works when delivered from the server and then adding JavaScript to improve it, so the baseline experience is available to everyone.: the page works when delivered from the server, and JavaScript makes it better. If JavaScript fails to load, each of these Kaksha features still works the plain way:

The practical rule is to send the working version and let the controller change it. A panel that the server sends with the hidden attribute and that only JavaScript can open is closed for good when the script fails; a panel sent open, or a <details>, is readable either way.

Accessible widgets need keyboard support and ARIA state. A disclosure button should be a <button> with aria-expanded toggled between true and false, and the panel gets the hidden attribute when collapsed, which hides it from sight and from screen readers alike. Text that changes as the user types should sit in a live regionlive region: An element marked with aria-live that screen readers monitor and announce when its content changes, so dynamic updates are heard without the user moving focus. (aria-live="polite") so screen readers announce the new value without interrupting. The fee form above uses an output element for its total, which many browsers already treat as a live region.

Decide where the state lives: Turbo alone or Stimulus

Turbo moves HTML the server renders: navigation, form submission, server-sent updates. Stimulus changes what the browser already holds. Before you write a controller, ask where the new state lives. If the server holds it (a saved record, a validation error, a row another user added), let Turbo carry it with a frame or a stream. If only the browser holds it (whether a panel is open, how many characters have been typed, how a number is formatted), a request per change is wasted latency, and a controller keeps it local.

A disclosure is therefore Turbo alone when its content has to come from the server, <details> when the text is already there and a plain toggle is enough, and Stimulus when the open state needs more than <details> gives. A server round trip for every interaction is acceptable on fast networks but annoying on slow ones, and a character counter that waited for the server would lag behind typing.

Practise: trace an action through a controller

Four short tasks cover the three objectives, then come the questions. The first three use any Rails 8.1 app:

1. Run bin/rails generate stimulus character_counter, read the identifier in the comment on line 3 of the new file, then write data-controller with that identifier on a form.
2. Give the controller a field and a count target, and an action input->character-counter#update on the field. Make update() write the length of this.fieldTarget.value into this.countTarget.
3. Log “connected” in connect() and “disconnected” in disconnect(), then swap the form with a Turbo Frame link and read the two messages in the browser console. Which comes first?
4. Without a browser, sort three features into “Turbo alone” or “Stimulus” and name where each state lives: a “saved” notice after a form post, a seat counter that follows the quantity field, and a “copy invoice number” button.

The questions below use the fee calculator: its HTML, its controller and the lifecycle when Turbo replaces the form. Pick an answer and its explanation opens straight away:

Interview questions

Warm-up: what does a Stimulus controller need to update a total when a quantity field changes?

A controller connected to the form element with data-controller. A value to hold the base fee (a number read from a data attribute). A target on the quantity input and another on the element that shows the total. An action on the quantity input, such as data-action="input->fee-calculator#calculate", that calls the calculate method whenever the field changes. The method reads the quantity from its target, multiplies, formats with Intl.NumberFormat, and writes the result to the total target.

Key takeaways

• A Stimulus controller is a JavaScript class that Stimulus attaches to any element carrying data-controller with the controller’s identifier.
• Actions, targets and values wire DOM events, named elements and typed data to the controller through data attributes, so HTML declares what matters and JavaScript does the work.
• Classes and outlets let the controller read CSS class names and reach other controllers without hard-coding identifiers.
• A Turbo swap runs disconnect() on the old controller and connect() on the new one, so behaviour survives navigation; anything connect() sets up outside the element, disconnect() must take down, or the listener multiplies with every visit.
• Progressive enhancement means the page works from the server and JavaScript improves it; accessible widgets need keyboard support, ARIA state and live regions.
• Ask where the state lives: Turbo carries state the server holds, and a Stimulus controller keeps state only the browser holds.