@hotwired/stimulus

What is @hotwired/stimulus?

@hotwired/stimulus is a JavaScript framework that enhances the interactivity of web applications by providing a lightweight, unobtrusive way to add behavior to HTML elements. It follows the principles of the Stimulus framework, which emphasizes simplicity and convention over configuration.

What are @hotwired/stimulus's main functionalities?

Controller Definition

Defines a Stimulus controller that logs a message to the console when connected to the DOM.

```javascript
import { Controller } from "@hotwired/stimulus";

export default class extends Controller {
  connect() {
    console.log("Hello, Stimulus!");
  }
}
```

Data Attributes

Uses data attributes to bind HTML elements to Stimulus controllers and actions.

```html
<div data-controller="example">
  <button data-action="click->example#sayHello">Click me</button>
</div>

<script>
  import { Application } from "@hotwired/stimulus";
  import ExampleController from "./example_controller";

  const application = Application.start();
  application.register("example", ExampleController);
</script>
```

Targets

Defines targets within a controller to easily reference and manipulate specific elements.

```html
<div data-controller="example">
  <input data-example-target="name" type="text">
  <button data-action="click->example#greet">Greet</button>
</div>

<script>
  import { Controller } from "@hotwired/stimulus";

  export default class extends Controller {
    static targets = [ "name" ];

    greet() {
      alert(`Hello, ${this.nameTarget.value}!`);
    }
  }
</script>
```

Other packages similar to @hotwired/stimulus

alpinejs

Alpine.js is a lightweight JavaScript framework that offers similar functionality to Stimulus by providing a way to add interactivity to HTML elements using declarative attributes. It is often compared to Stimulus for its simplicity and ease of use.

vue

Vue.js is a more comprehensive JavaScript framework that offers a wide range of features for building interactive web applications. While it can be used for similar purposes as Stimulus, it is more powerful and complex, making it suitable for larger applications.

react

React is a popular JavaScript library for building user interfaces. It offers a component-based architecture and is often used for building complex, interactive web applications. Compared to Stimulus, React is more powerful but also more complex and requires a different approach to development.

README

Stimulus

A modest JavaScript framework for the HTML you already have

Stimulus is a JavaScript framework with modest ambitions. It doesn't seek to take over your entire front-end—in fact, it's not concerned with rendering HTML at all. Instead, it's designed to augment your HTML with just enough behavior to make it shine. Stimulus pairs beautifully with Turbo to provide a complete solution for fast, compelling applications with a minimal amount of effort.

How does it work? Sprinkle your HTML with controller, target, and action attributes:

<div data-controller="hello">
  <input data-hello-target="name" type="text">

  <button data-action="click->hello#greet">Greet</button>

  <span data-hello-target="output"></span>
</div>

Then write a compatible controller. Stimulus brings it to life automatically:

// hello_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = [ "name", "output" ]

  greet() {
    this.outputTarget.textContent =
      `Hello, ${this.nameTarget.value}!`
  }
}

Stimulus continuously watches the page, kicking in as soon as attributes appear or disappear. It works with any update to the DOM, regardless of whether it comes from a full page load, a Turbo page change, or an Ajax request. Stimulus manages the whole lifecycle.

You can write your first controller in five minutes by following along in the Stimulus Handbook.

You can read more about why we created this new framework in The Origin of Stimulus.

Installing Stimulus

You can use Stimulus with any asset packaging systems. And if you prefer no build step at all, just drop a <script> tag on the page and get right down to business.

See the Installation Guide for detailed instructions.

Getting Help

Looking for the docs? Once you've read through the Handbook, consult the Stimulus Reference for API details.

Have a question about Stimulus? Connect with other Stimulus developers on the Hotwire Discourse community forum.

Contributing Back

Find a bug? Head over to our issue tracker and we'll do our best to help. We love pull requests, too!

We expect all Stimulus contributors to abide by the terms of our Code of Conduct.

Development

• Fork the project locally
• yarn install
• yarn start - to run the local dev server with examples
• yarn test - to run the unit tests
• yarn lint - to run the linter with ESLint
• yarn format - to format changes with Prettier

Acknowledgments

Stimulus is MIT-licensed open-source software from Basecamp, the creators of Ruby on Rails.

Continuous integration VMs generously provided by Sauce Labs.

---

© 2023 Basecamp, LLC.