stimulus

library0.2.1jsnpmunverified

Stimulus is a modest, lightweight JavaScript framework designed by Basecamp to augment existing HTML with behavior, rather than taking over the entire front-end rendering. It operates on the principle of connecting JavaScript objects (controllers) to elements on the page using simple HTML data attributes (`data-controller`, `data-action`, `data-target`). It promotes a 'HTML-first' development approach, making it particularly popular in environments like Ruby on Rails with Hotwire (Turbo + Stimulus) where server-rendered HTML is prevalent. The current stable version is 3.2.2. Stimulus is actively maintained with regular updates and follows semantic versioning, introducing new features and occasional breaking changes between major versions. Its key differentiators include its small footprint, convention-over-configuration philosophy, and focus on enhancing server-rendered HTML rather than building single-page applications.

web-framework

npm install stimulus

package ↗homepage ↗

INSTALL

IMPORT

SIG · STIMULUS

stimulus

web-frameworkjavascriptv0.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Application

✓ import { Application } from '@hotwired/stimulus'

✗ import { Application } from 'stimulus'

The official package name changed from `stimulus` to `@hotwired/stimulus` in version 3. Always use `@hotwired/stimulus` for v3+ projects.

Controller

✓ import { Controller } from '@hotwired/stimulus'

✗ import { Controller } from 'stimulus'

Base class for all Stimulus controllers. Ensure you import from the correct `@hotwired/stimulus` package in v3+ projects.

SpecificController

✓ import SpecificController from './controllers/specific_controller'

✗ const SpecificController = require('./controllers/specific_controller')

Stimulus controllers are typically exported as default ES Modules. CommonJS `require` is generally not used for individual controllers in modern Stimulus setups, especially with import maps or bundlers configured for ES Modules.

This quickstart demonstrates a basic 'Hello World' Stimulus application, showing how to connect a controller to HTML, define targets, and handle actions.

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Stimulus Hello World</title> </head> <body> <div data-controller="hello"> <input data-hello-target="name" type="text" placeholder="Your name"> <button data-action="click->hello#greet">Greet</button> <p data-hello-target="output"></p> </div> <script type="module"> import { Application, Controller } from '@hotwired/stimulus'; // Create a Stimulus application instance const application = Application.start(); // Define and register the 'hello' controller class HelloController extends Controller { static targets = ['name', 'output']; connect() { console.log('Hello controller connected!'); this.outputTarget.textContent = 'Enter your name and click greet!'; } greet() { const name = this.nameTarget.value; this.outputTarget.textContent = `Hello, ${name || 'World'}!`; } } application.register('hello', HelloController); </script> </body> </html>

Debug

Known issues

breakingThe Stimulus npm package name changed from `stimulus` to `@hotwired/stimulus` with the release of Stimulus 3. Projects upgrading to v3+ must update their `package.json` and all import paths.

fix

Update `package.json` to `"@hotwired/stimulus": "^3.0.0"` and change all `import { ... } from 'stimulus'` statements to `import { ... } from '@hotwired/stimulus'`.

affects: >=3.0.0

breakingStimulus 3 dropped support for Internet Explorer 11. Projects requiring IE11 compatibility should remain on Stimulus 2 or implement polyfills and ensure their JavaScript transpilation targets ES6+.

fix

If IE11 support is critical, either remain on Stimulus 2.x or earlier, or adjust your build pipeline (e.g., Babel `browserslist` configuration) to transpile your application's JavaScript to ES6+ and ensure necessary polyfills are included.

affects: >=3.0.0

breakingIn Stimulus 2.0, the syntax for target attributes changed from `data-target="identifier.name"` to `data-[identifier]-target="name"`. While Stimulus 2 provided a console warning for the old syntax, Stimulus 3 fully expects the new scoped syntax.

fix

Migrate all `data-target` attributes to the new `data-[controller-identifier]-target` format. For example, `data-target="hello.output"` becomes `data-hello-target="output"`.

affects: >=2.0.0

deprecatedThe `data` map API (e.g., `this.data.get('key')`) from Stimulus 1.x was replaced by the more robust 'Values API' and 'CSS Classes API' in Stimulus 2.0. While it might still function, it is no longer documented and considered internal; migration is strongly recommended.

fix

Refactor controllers to use the `static values = { key: String }` declaration and access values via `this.keyValue`, and `static classes = { name: String }` for `this.nameClass` properties.

affects: >=2.0.0

Errors

Common errors & fixes

Uncaught (in promise) TypeError: class constructors must be invoked with 'new'

This error often occurs when upgrading to Stimulus 3+ if the application's JavaScript is still being transpiled to ES5, but Stimulus 3 itself is compiled to ES6+. ES5 constructors cannot correctly extend ES6 classes.

fix

Update your JavaScript build configuration (e.g., Babel `browserslist` in `package.json`) to target ES6+ for your application code, explicitly excluding IE11 if it's no longer supported. For example, add `"not IE 11"` to your `browserslist` configuration.

Stimulus: 'hello' controller not found. Check your `data-controller` attribute and ensure the controller is registered.

The `data-controller` attribute in HTML does not match a registered controller identifier, or the controller file is not correctly imported and registered with the Stimulus application.

fix

Verify that the `data-controller` attribute in your HTML matches the identifier used in `application.register('your-identifier', YourController)` (e.g., `hello` for `hello_controller.js`). Ensure your controller file is correctly imported and that `application.register()` is called.

this.someTarget is undefined

This typically means a `data-[controller]-target="some"` attribute is missing from the HTML element, or the `static targets = ['some']` declaration is missing/incorrect in the controller.

fix

Ensure the `data-[controller-identifier]-target="some-target-name"` attribute is present in your HTML for the element you wish to access. Also, confirm that `static targets = ['someTargetName']` is correctly defined within your Stimulus controller, using camelCase for the property name.

Upgrade

Version history

0.2.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

3 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/stimulus ↗

homepagehttps://stimulus.hotwired.dev ↗