Skip to content

Installing Stimulus in Your Application

To install Stimulus in your application, add the stimulus npm package to your JavaScript bundle. Or, load stimulus.umd.js in a <script> tag.

Using webpack

Stimulus integrates with the webpack asset packager to automatically load controller files from a folder in your app.

Call webpack’s require.context helper with the path to the folder containing your Stimulus controllers. Then, pass the resulting context to the Application#load method using the definitionsFromContext helper:

// src/application.js
import { Application } from "stimulus"
import { definitionsFromContext } from "stimulus/webpack-helpers"

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

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

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

const application = Application.start()
application.register("hello", HelloController)
application.register("clipboard", ClipboardController)

Using Babel

If you’re using Babel with your build system, you’ll need to add the @babel/plugin-proposal-class-properties plugin to your configuration:

{
  "presets": ["@babel/preset-env"],
  "plugins": ["@babel/plugin-proposal-class-properties"]
}

Or, by enabling the shippedProposals option with Babel ^7.10.0:

{
  "presets": [["@babel/preset-env", { "shippedProposals": true }]]
}

Using Without a Build System

If you prefer not to use a build system, you can load Stimulus in a <script> tag and it will be globally available through the window.Stimulus object.

Define targets using static get targets() methods instead of static targets = […] class properties, which aren’t supported natively yet.

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <script src="https://unpkg.com/stimulus/dist/stimulus.umd.js"></script>
  <script>
    (() => {
      const application = Stimulus.Application.start()

      application.register("hello", class extends Stimulus.Controller {
        static get targets() {
          return [ "name" ]
        }

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

Browser Support

Stimulus supports all evergreen, self-updating desktop and mobile browsers out of the box.

If your application needs to support older browsers like Internet Explorer 11, include the @stimulus/polyfills package before loading Stimulus.

import "@stimulus/polyfills"
import { Application } from "stimulus"

const application = Application.start()
// …