# Stimulus — Modest JavaScript Framework for Server-Rendered HTML

> Stimulus is a JavaScript framework by Basecamp that connects behavior to existing server-rendered HTML via data attributes, without requiring a full client-side rendering layer or build step.

## Install

Save in your project root:

# Stimulus — Modest JavaScript Framework for Server-Rendered HTML

## Quick Use
```bash
npm install @hotwired/stimulus
```
```javascript
import { Application, Controller } from "@hotwired/stimulus"
const app = Application.start()
app.register("hello", class extends Controller {
  static targets = ["name"]
  greet() { alert("Hello, " + this.nameTarget.value) }
})
```
```html
<div data-controller="hello">
  <input data-hello-target="name" type="text">
  <button data-action="click->hello#greet">Greet</button>
</div>
```

## Introduction
Stimulus is a JavaScript framework created by the Basecamp team as part of the Hotwire stack. Instead of taking over the entire page with client-side rendering, Stimulus attaches behavior to existing HTML elements through data attributes. It is designed for server-rendered applications where most HTML comes from Rails, Django, Laravel, or any backend template engine.

## What Stimulus Does
- Connects JavaScript controllers to DOM elements via `data-controller` attributes
- Binds user events to controller methods with `data-action` descriptors
- References DOM elements through typed targets defined with `data-*-target`
- Manages reactive values that trigger callbacks when changed
- Automatically mounts and unmounts controllers as elements enter or leave the DOM

## Architecture Overview
Stimulus observes the DOM using MutationObserver. When an element with a `data-controller` attribute appears, Stimulus instantiates the matching controller class and connects it. The controller accesses child elements via declared targets, listens for events via action descriptors, and stores state in values that sync to data attributes. When the element is removed, the controller disconnects and cleans up. No virtual DOM or template compilation is involved.

## Self-Hosting & Configuration
- Install via npm (`@hotwired/stimulus`) or include from a CDN
- Register controllers manually or use the webpack/esbuild loader for auto-registration
- Place controller files in `app/javascript/controllers/` (Rails convention) or any directory
- Name controllers to match data attributes: `hello_controller.js` maps to `data-controller="hello"`
- Works with any backend; no bundler required for basic usage with importmaps

## Key Features
- HTML-first approach augments server-rendered markup without replacing it
- Automatic lifecycle management as elements are added or removed from the DOM
- Values API syncs controller state to data attributes for persistence and SSR hydration
- CSS class management with declared outlet connections between controllers
- Zero framework lock-in: works alongside any other JavaScript or backend framework

## Comparison with Similar Tools
- **Alpine.js** — Similar HTML-attribute-driven approach, but inlines JS expressions in markup rather than separate controller files
- **htmx** — Extends HTML with AJAX and WebSocket attributes, focuses on server responses rather than client-side behavior
- **React** — Full client-side rendering framework, takes over DOM management, different mental model
- **Vue** — Progressive framework that can enhance HTML but encourages component-based architecture
- **Turbo** — Stimulus's sibling in Hotwire, handles page navigation and frame updates while Stimulus handles behavior

## FAQ
**Q: Do I need Rails to use Stimulus?**
A: No. Stimulus works with any backend or static HTML. It was designed at Basecamp for Rails but has no Rails dependency.

**Q: How does Stimulus relate to Hotwire?**
A: Hotwire is a collection of tools: Turbo (page navigation and frames), Stimulus (JavaScript behavior), and Strada (native mobile bridges). They work together but can be used independently.

**Q: Can Stimulus replace React or Vue?**
A: Stimulus is not designed for complex client-rendered SPAs. It excels at adding interactivity to server-rendered pages where a full SPA framework would be overkill.

**Q: How large is Stimulus?**
A: The Stimulus runtime is roughly 3 KB gzipped, making it one of the smallest JavaScript frameworks available.

## Sources
- https://github.com/hotwired/stimulus
- https://stimulus.hotwired.dev/handbook/introduction

---
Source: https://tokrepo.com/en/workflows/2da2673c-42ff-11f1-9bc6-00163e2b0d79
Author: AI Open Source