{"id":12079,"library":"stimulus","title":"Stimulus JavaScript Framework","description":"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.","status":"active","version":"3.2.2","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install stimulus","lang":"bash","label":"npm"},{"cmd":"yarn add stimulus","lang":"bash","label":"yarn"},{"cmd":"pnpm add stimulus","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The official package name changed from `stimulus` to `@hotwired/stimulus` in version 3. Always use `@hotwired/stimulus` for v3+ projects.","wrong":"import { Application } from 'stimulus'","symbol":"Application","correct":"import { Application } from '@hotwired/stimulus'"},{"note":"Base class for all Stimulus controllers. Ensure you import from the correct `@hotwired/stimulus` package in v3+ projects.","wrong":"import { Controller } from 'stimulus'","symbol":"Controller","correct":"import { Controller } from '@hotwired/stimulus'"},{"note":"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.","wrong":"const SpecificController = require('./controllers/specific_controller')","symbol":"SpecificController","correct":"import SpecificController from './controllers/specific_controller'"}],"quickstart":{"code":"\n\n\n\n \n \n Stimulus Hello World\n\n\n
\n \n \n \n
\n\n \n\n","lang":"typescript","description":"This quickstart demonstrates a basic 'Hello World' Stimulus application, showing how to connect a controller to HTML, define targets, and handle actions."},"warnings":[{"fix":"Update `package.json` to `\"@hotwired/stimulus\": \"^3.0.0\"` and change all `import { ... } from 'stimulus'` statements to `import { ... } from '@hotwired/stimulus'`.","message":"The 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"Stimulus 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+.","severity":"breaking","affected_versions":">=3.0.0"},{"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\"`.","message":"In 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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"The `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.","severity":"deprecated","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Uncaught (in promise) TypeError: class constructors must be invoked with 'new'"},{"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.","cause":"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.","error":"Stimulus: 'hello' controller not found. Check your `data-controller` attribute and ensure the controller is registered."},{"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.","cause":"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.","error":"this.someTarget is undefined"}],"ecosystem":"npm"}