Skip to content

Installing Stimulus in Your Application

To install Stimulus in your application, add the @hotwired/stimulus npm package to your JavaScript bundle. Or, import stimulus.js in a <script type="module"> tag.

﹟ Using Stimulus for Rails

If you’re using Stimulus for Rails together with an import map, the integration will automatically load all controller files from app/javascript/controllers.

﹟ Controller Filenames Map to Identifiers

Name your controller files [identifier]_controller.js, where identifier corresponds to each controller’s data-controller identifier in your HTML.

Stimulus for Rails conventionally separates multiple words in filenames using underscores. Each underscore in a controller’s filename translates to a dash in its identifier.

You may also namespace your controllers using subfolders. Each forward slash in a namespaced controller file’s path becomes two dashes in its identifier.

If you prefer, you may use dashes instead of underscores anywhere in a controller’s filename. Stimulus treats them identically.

If your controller file is named… its identifier will be…
clipboard_controller.js clipboard
date_picker_controller.js date-picker
users/list_item_controller.js users--list-item
local-time-controller.js local-time

﹟ Using Webpack Helpers

If you’re using Webpack as your JavaScript bundler, you can use the @hotwired/stimulus-webpack-helpers package to get the same form of autoloading behavior as Stimulus for Rails. First add the package, then use it like this:

import { Application } from "@hotwired/stimulus"
import { definitionsFromContext } from "@hotwired/stimulus-webpack-helpers"

window.Stimulus = Application.start()
const context = require.context("./controllers", true, /\.js$/)
Stimulus.load(definitionsFromContext(context))

﹟ Using Other Build Systems

Stimulus works with other build systems too, but without support for controller autoloading. Instead, you must explicitly load and register controller files with your application instance:

// src/application.js
import { Application } from "@hotwired/stimulus"

import HelloController from "./controllers/hello_controller"
import ClipboardController from "./controllers/clipboard_controller"

window.Stimulus = Application.start()
Stimulus.register("hello", HelloController)
Stimulus.register("clipboard", ClipboardController)

If you’re using stimulus-rails with a builder like esbuild, you can use the stimulus:manifest:update Rake task and ./bin/rails generate stimulus [controller] generator to keep a controller index file located at app/javascript/controllers/index.js automatically updated.

﹟ Using Without a Build System

If you prefer not to use a build system, you can load Stimulus in a <script type="module"> tag:

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <script type="module">
    import { Application, Controller } from "https://unpkg.com/@hotwired/stimulus/dist/stimulus.js"
    window.Stimulus = Application.start()

    Stimulus.register("hello", class extends Controller {
      static targets = [ "name" ]

      connect() {
      }
    })
  </script>
</head>
<body>
  <div data-controller="hello">
    <input data-hello-target="name" type="text">
    …
  </div>
</body>
</html>

﹟ Overriding Attribute Defaults

In case Stimulus data-* attributes conflict with another library in your project, they can be overridden when creating the Stimulus Application.

These core Stimulus attributes can be overridden (see: schema.ts):

// src/application.js
import { Application, defaultSchema } from "@hotwired/stimulus"

const customSchema = {
  ...defaultSchema,
  actionAttribute: 'data-stimulus-action'
}

window.Stimulus = Application.start(document.documentElement, customSchema);

﹟ Error handling

All calls from Stimulus to your application’s code are wrapped in a try ... catch block.

If your code throws an error, it will be caught by Stimulus and logged to the browser console, including extra detail such as the controller name and event or lifecycle function being called. If you use an error tracking system that defines window.onerror, Stimulus will also pass the error on to it.

You can override how Stimulus handles errors by defining Application#handleError:

// src/application.js
import { Application } from "@hotwired/stimulus"
window.Stimulus = Application.start()

Stimulus.handleError = (error, message, detail) => {
  console.warn(message, detail)
  ErrorTrackingSystem.captureException(error)
}

﹟ Debugging

If you’ve assigned your Stimulus application to window.Stimulus, you can turn on debugging mode from the console with Stimulus.debug = true. You can also set this flag when you’re configuring your application instance in the source code.

﹟ Browser Support

Stimulus supports all evergreen, self-updating desktop and mobile browsers out of the box. Stimulus 3+ does not support Internet Explorer 11 (but you can use Stimulus 2 with the @stimulus/polyfills for that).