stimulus

What is stimulus?

Stimulus is a JavaScript framework that enhances the behavior of HTML elements by connecting them to JavaScript controllers. It is designed to work with the HTML you already have, making it easy to add interactivity to your web applications without the need for a complex setup.

What are stimulus's main functionalities?

Controller Initialization

This feature allows you to initialize a Stimulus controller and connect it to HTML elements. The controller listens for events (like a button click) and executes the corresponding JavaScript function.

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

<!-- JavaScript -->
import { Controller } from "stimulus";

export default class extends Controller {
  sayHello() {
    alert("Hello, Stimulus!");
  }
}
```

Data Attributes

Stimulus uses data attributes to pass information from HTML to JavaScript. This example demonstrates how to use data attributes to store and retrieve data within a controller.

```html
<!-- HTML -->
<div data-controller="example" data-example-name="Stimulus">
  <button data-action="click->example#greet">Greet</button>
</div>

<!-- JavaScript -->
import { Controller } from "stimulus";

export default class extends Controller {
  greet() {
    const name = this.data.get("name");
    alert(`Hello, ${name}!`);
  }
}
```

Targets

Targets in Stimulus allow you to easily reference specific elements within your controller. This example shows how to use targets to get the value of an input field and use it in a function.

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

<!-- JavaScript -->
import { Controller } from "stimulus";

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

  greet() {
    const name = this.nameTarget.value;
    alert(`Hello, ${name}!`);
  }
}
```

Other packages similar to stimulus

alpinejs

Alpine.js is a lightweight JavaScript framework that offers similar functionality to Stimulus. It allows you to add interactivity to your HTML with minimal JavaScript. Compared to Stimulus, Alpine.js is more declarative and often requires less boilerplate code.

htmx

HTMX is a library that allows you to access modern browser features directly from HTML, making it easy to add AJAX, CSS Transitions, WebSockets, and Server-Sent Events to your web applications. While Stimulus focuses on connecting JavaScript controllers to HTML, HTMX focuses on enhancing HTML with modern web capabilities.

vue

Vue.js is a progressive JavaScript framework for building user interfaces. While it is more feature-rich and complex compared to Stimulus, it offers a similar approach to enhancing HTML with reactive data binding and component-based architecture.

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 Turbolinks to provide a complete solution for fast, compelling applications with a minimal amount of effort.

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

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

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

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

export default class extends Controller {
  greet() {
    console.log(`Hello, ${this.name}!`)
  }

  get name() {
    return this.targets.find("name").value
  }
}

Stimulus continuously watches the page, kicking in as soon as magic attributes appear or disappear. It works with any update to the DOM, regardless of whether it comes from a full page load, a Turbolinks 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

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

You can use Stimulus with other asset packaging systems, too. 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.

Contributing Back

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

Have a question about Stimulus? Find a bug? Think the documentation could use some improvement? 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.

---

© 2018 Basecamp, LLC.