Stimulus

https://stimulus.hotwired.dev
Admin
Stimulus is a modest JavaScript framework designed to augment existing HTML with behavior. It...
Tokens:16,609
Snippets:233
Trust Score:9.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Clone and Start Stimulus Starter Project

Source: https://stimulus.hotwired.dev/handbook/hello-stimulus

Instructions for cloning the stimulus-starter project, installing dependencies, and starting the development server.

```bash
git clone https://github.com/hotwired/stimulus-starter.git
cd stimulus-starter
yarn install
yarn start
```

--------------------------------

### HTML for Content Loader with Action Parameters

Source: https://stimulus.hotwired.dev/handbook/working-with-external-resources

Example HTML demonstrating how to use data attributes to specify different URLs for the `content-loader` controller's `load` action.

```html
<div data-controller="content-loader">
  <a href="#" data-content-loader-url-param="/messages.html" data-action="content-loader#load">Messages</a>
  <a href="#" data-content-loader-url-param="/comments.html" data-action="content-loader#load">Comments</a>
</div>
```

--------------------------------

### HTML with Initial State Attribute

Source: https://stimulus.hotwired.dev/handbook/managing-state

Adds a 'data-index' attribute to the controller's element to specify the starting slide.

```html
<div data-controller="slideshow" data-index="1">

```

--------------------------------

### Multiple Actions on an Element

Source: https://stimulus.hotwired.dev/reference/actions

An example of an input element with multiple actions defined for different events: 'focus' and 'input'. Actions are invoked in the order they appear.

```html
<input type="text" data-action="focus->field#highlight input->search#update">
```

--------------------------------

### Controller Scope Example

Source: https://stimulus.hotwired.dev/reference/controllers

Illustrates the scope of a Stimulus controller, including its associated element and children.

```html
<main>
  <div data-controller="reference">
    <h1>Reference</h1>
  </div>
</main>
```

--------------------------------

### Example Outlet Attribute

Source: https://stimulus.hotwired.dev/reference/outlets

An example of an outlet attribute in HTML, where the 'chat' controller defines an outlet for 'user-status' controllers matching the '.online-user' selector.

```html
<div data-controller="chat" data-chat-user-status-outlet=".online-user"></div>
```

--------------------------------

### Complete Content Loader Stimulus Controller

Source: https://stimulus.hotwired.dev/handbook/working-with-external-resources

A full Stimulus controller example that loads content from a URL and refreshes it at a specified interval, managing the timer with lifecycle callbacks.

```javascript
// src/controllers/content_loader_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static values = { url: String, refreshInterval: Number }

  connect() {
    this.load()

    if (this.hasRefreshIntervalValue) {
      this.startRefreshing()
    }
  }

  disconnect() {
    this.stopRefreshing()
  }

  load() {
    fetch(this.urlValue)
      .then(response => response.text())
      .then(html => this.element.innerHTML = html)
  }

  startRefreshing() {
    this.refreshTimer = setInterval(() => {
      this.load()
    }, this.refreshIntervalValue)
  }

  stopRefreshing() {
    if (this.refreshTimer) {
      clearInterval(this.refreshTimer)
    }
  }
}
```

--------------------------------

### Registering a Custom Action Option (:open)

Source: https://stimulus.hotwired.dev/reference/actions

Shows how to register a custom action option named 'open' using Application.registerActionOption. This example routes events only when a <details> element is toggled open.

```javascript
import { Application } from "@hotwired/stimulus"

const application = Application.start()

application.registerActionOption("open", ({ event }) => {
  if (event.type == "toggle") {
    return event.target.open == true
  } else {
    return true
  }
})
```

--------------------------------

### Stimulus Controller, Action, and Target Example

Source: https://stimulus.hotwired.dev/handbook/origin

This HTML structure demonstrates how Stimulus uses data attributes to define a controller, an action, and a target. The `data-controller` attribute initializes the Stimulus controller, `data-action` specifies the event and method to trigger, and `data-*-target` attributes identify elements within the controller's scope.

```html
<div data-controller="clipboard">
  PIN: <input data-clipboard-target="source" type="text" value="1234" readonly>
  <button data-action="clipboard#copy">Copy to Clipboard</button>
</div>
```

--------------------------------

### Apply a loading class to an element

Source: https://stimulus.hotwired.dev/reference/css-classes

This example shows how a CSS class can be used to indicate a busy state. The class is applied directly in HTML.

```html
<form data-controller="search" class="search--busy">

```

--------------------------------

### Target Attribute and Name Example

Source: https://stimulus.hotwired.dev/reference/targets

Illustrates the `data-search-target` attribute, where 'results' is a target name that can be referenced within the 'search' controller.

```html
<div data-controller="search">
  <div data-search-target="results"></div>
</div>
```

--------------------------------

### Start Refresh Timer in Stimulus Controller

Source: https://stimulus.hotwired.dev/handbook/working-with-external-resources

Starts a recurring timer to periodically call the `load` method. Ensure `refreshIntervalValue` is set for this to function.

```javascript
startRefreshing() {
    this.refreshTimer = setInterval(() => {
      this.load()
    }, this.refreshIntervalValue)
  }
```

--------------------------------

### Conditional Target Access

Source: https://stimulus.hotwired.dev/reference/targets

This example shows how to safely access a target element by first checking for its existence using the `has[Name]Target` property before attempting to manipulate it.

```javascript
if (this.hasResultsTarget) {
  this.resultsTarget.innerHTML = "…"
}
```

--------------------------------

### Implement Hello Controller Logic

Source: https://stimulus.hotwired.dev/handbook/hello-stimulus

This JavaScript controller defines the 'name' target and implements the 'greet' action to read the input value and log a greeting.

```javascript
// src/controllers/hello_controller.js
import { Controller } from "@hotwired/stimulus"

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

  greet() {
    const element = this.nameTarget
    const name = element.value
    console.log(`Hello, ${name}!")
  }
}
```

--------------------------------

### Define Hello Controller with Name Target

Source: https://stimulus.hotwired.dev/handbook/hello-stimulus

This HTML sets up a Stimulus controller and defines a 'name' target for an input field. The 'greet' action is attached to a button.

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

--------------------------------

### Initializing Slideshow with Data Attribute

Source: https://stimulus.hotwired.dev/handbook/managing-state

Demonstrates how to set an initial state for the slideshow controller by reading a 'data-index' attribute from the controller's element.

```javascript
initialize() {
  this.index = Number(this.element.dataset.index)
  this.showCurrentSlide()
}
```

--------------------------------

### Custom Stimulus Schema for Key Mappings

Source: https://stimulus.hotwired.dev/reference/actions

Demonstrates how to create a custom Stimulus schema to map additional keys, like '@' to 'at'.

```javascript
import { Application, defaultSchema } from "@hotwired/stimulus"

const customSchema = {
  ...defaultSchema,
  keyMappings: { ...defaultSchema.keyMappings, at: "@" },
}

const app = Application.start(document.documentElement, customSchema)
```

--------------------------------

### Accessing Outlet Controller Properties

Source: https://stimulus.hotwired.dev/reference/outlets

Illustrates how to access properties and targets of a referenced outlet controller instance.

```javascript
this.userStatusOutlet.idValue
this.userStatusOutlet.imageTarget
this.userStatusOutlet.activeClasses
```

--------------------------------

### Load Stimulus via Script Tag (No Build System)

Source: https://stimulus.hotwired.dev/handbook/installing

Load Stimulus directly in an HTML file using a script tag with type="module" if you are not using a build system.

```html
<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <script type="module">
    import { Application, Controller } from "https://unpkg.com/@hotwired/stimulus/dist/stimulus.js"
    window.Stimulus = Application.start()

    Stimulus.register("hello", class extends Controller {
      static targets = [ "name" ]

      connect() {
      }
    })
  </script>
</head>
<body>
  <div data-controller="hello">
    <input data-hello-target="name" type="text">
    …
  </div>
</body>
</html>
```

--------------------------------

### Invoking Outlet Controller Functions

Source: https://stimulus.hotwired.dev/reference/outlets

Shows how to call functions defined on a referenced outlet controller instance.

```javascript
// user_status_controller.js

export default class extends Controller {
  markAsSelected(event) {
    // ...
  }
}

// chat_controller.js

export default class extends Controller {
  static outlets = [ "user-status" ]

  selectAll(event) {
    this.userStatusOutlets.forEach(status => status.markAsSelected(event))
  }
}
```

--------------------------------

### Initialize a Stimulus Controller

Source: https://stimulus.hotwired.dev/handbook/hello-stimulus

Creates a basic Stimulus controller by extending the framework's Controller class.

```javascript
// src/controllers/hello_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
}
```

--------------------------------

### Map multiple logical classes to kebab-case HTML attributes

Source: https://stimulus.hotwired.dev/reference/css-classes

Shows how to map the 'loading' and 'noResults' logical classes to their respective kebab-case data attributes in the HTML. This follows Stimulus naming conventions.

```html
<form data-controller="search"
      data-search-loading-class="search--busy"
      data-search-no-results-class="search--empty">

```

--------------------------------

### Multiple Reusable Clipboard Controllers

Source: https://stimulus.hotwired.dev/handbook/building-something-real

Demonstrates how multiple instances of the same Stimulus controller can exist on a page. Each 'div' with 'data-controller="clipboard"' represents an independent instance, allowing for multiple copyable PINs.

```html
<div data-controller="clipboard">
  PIN: <input data-clipboard-target="source" type="text" value="3737" readonly>
  <button data-action="clipboard#copy">Copy to Clipboard</button>
</div>
```

--------------------------------

### Basic Controller with Connect Method

Source: https://stimulus.hotwired.dev/reference/lifecycle-callbacks

Define a Stimulus controller and implement the connect method. This method is invoked by Stimulus anytime the controller is connected to the DOM.

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

export default class extends Controller {
  connect() {
    // …
  }
}
```

--------------------------------

### Initialize Stimulus Clipboard Controller

Source: https://stimulus.hotwired.dev/handbook/building-something-real

This JavaScript initializes a Stimulus controller. It imports the Controller class and exports a default class that extends it, providing an empty copy method.

```javascript
// src/controllers/clipboard_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  copy() {
  }
}
```

--------------------------------

### Define and use multiple logical CSS classes

Source: https://stimulus.hotwired.dev/reference/css-classes

Demonstrates defining both 'loading' and 'noResults' logical classes and conditionally applying 'noResultsClass' when no results are found.

```javascript
export default class extends Controller {
  static classes = [ "loading", "noResults" ]

  loadResults() {
    // …
    if (results.length == 0) {
      this.element.classList.add(this.noResultsClass)
    }
  }
}

```

--------------------------------

### Basic Action Declaration

Source: https://stimulus.hotwired.dev/reference/actions

Connects a 'click' event on a button to the 'next' method of the 'gallery' controller.

```html
<div data-controller="gallery">
  <button data-action="click->gallery#next">…</button>
</div>
```

--------------------------------

### Registering a Custom Action Option (:!open)

Source: https://stimulus.hotwired.dev/reference/actions

Illustrates registering a custom action option 'open' with a '!' prefix to handle cases where an element is toggled closed. The 'value' argument in the callback determines the condition.

```javascript
import { Application } from "@hotwired/stimulus"

const application = Application.start()

application.registerActionOption("open", ({ event, value }) => {
  if (event.type == "toggle") {
    return event.target.open == value
  } else {
    return true
  }
})
```

--------------------------------

### Load HTML content from a URL

Source: https://stimulus.hotwired.dev/handbook/working-with-external-resources

Use this controller to fetch and insert HTML from a specified URL into its element. Configure the URL via `data-content-loader-url-value`.

```html
<div data-controller="content-loader"
     data-content-loader-url-value="/messages.html"></div>
```

```html
<ol>
  <li>New Message: Stimulus Launch Party</li>
  <li>Overdue: Finish Stimulus 1.0</li>
</ol>
```

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

export default class extends Controller {
  static values = { url: String }

  connect() {
    this.load()
  }

  load() {
    fetch(this.urlValue)
      .then(response => response.text())
      .then(html => this.element.innerHTML = html)
  }
}
```

--------------------------------

### Accessing Nested Outlets

Source: https://stimulus.hotwired.dev/reference/outlets

Demonstrates how to correctly access nested controller outlets by omitting namespace delimiters in the property name.

```javascript
// chat_controller.js

export default class extends Controller {
  static outlets = [ "admin--user-status" ]

  selectAll(event) {
    // returns undefined
    this.admin__UserStatusOutlets

    // returns controller reference
    this.adminUserStatusOutlets
  }
}
```

--------------------------------

### HTML Structure for Outlets

Source: https://stimulus.hotwired.dev/reference/outlets

This HTML demonstrates the structure where a 'chat' controller references '.online-user' elements, which are instances of the 'user-status' controller.

```html
<div>
  <div class="online-user" data-controller="user-status">...</div>
  <div class="online-user" data-controller="user-status">...</div>
  ...
</div>

...

<div data-controller="chat" data-chat-user-status-outlet=".online-user">
  ...
</div>
```

--------------------------------

### Manually Register Controllers with Stimulus

Source: https://stimulus.hotwired.dev/handbook/installing

For build systems other than Webpack, manually register your controllers. This approach requires explicit imports and registration calls.

```javascript
// src/application.js
import { Application } from "@hotwired/stimulus"

import HelloController from "./controllers/hello_controller"
import ClipboardController from "./controllers/clipboard_controller"

window.Stimulus = Application.start()
Stimulus.register("hello", HelloController)
Stimulus.register("clipboard", ClipboardController)
```

--------------------------------

### Passing Parameters to Stimulus Actions

Source: https://stimulus.hotwired.dev/reference/actions

Demonstrates how to pass multiple parameters of different types (Number, String, Object, Boolean) to a Stimulus action using data attributes. Only actions declared on the same element as the parameters will receive them.

```html
<div data-controller="item spinner">
  <button data-action="item#upvote spinner#start" 
    data-item-id-param="12345" 
    data-item-url-param="/votes"
    data-item-payload-param='{"value":"1234567"}' 
    data-item-active-param="true">…</button>
</div>
```

--------------------------------

### Defining Outlets in Controller Class

Source: https://stimulus.hotwired.dev/reference/outlets

Shows how to declare which controller identifiers can be used as outlets within a Stimulus controller using the `static outlets` array.

```javascript
// chat_controller.js

export default class extends Controller {
  static outlets = [ "user-status" ]

  connect () {
    this.userStatusOutlets.forEach(status => ...)
  }
}
```

--------------------------------

### Accessing Outlet Element Properties and Attributes

Source: https://stimulus.hotwired.dev/reference/outlets

Demonstrates how to interact with the controller element associated with an outlet, accessing its properties and attributes.

```javascript
this.userStatusOutletElement.dataset.value
this.userStatusOutletElement.getAttribute("id")
this.userStatusOutletElements.map(status => status.hasAttribute("selected"))
```

--------------------------------

### Configure Stimulus with Webpack Autoloading

Source: https://stimulus.hotwired.dev/handbook/installing

Use this snippet with Webpack to enable controller autoloading. It requires the @hotwired/stimulus-webpack-helpers package.

```javascript
import { Application } from "@hotwired/stimulus"
import { definitionsFromContext } from "@hotwired/stimulus-webpack-helpers"

window.Stimulus = Application.start()
const context = require.context("./controllers", true, /\.js$/)
Stimulus.load(definitionsFromContext(context))
```

--------------------------------

### Using Action Options in Stimulus

Source: https://stimulus.hotwired.dev/reference/actions

Demonstrates how to append action options like :passive, :capture, :once, and :!passive to action descriptors to modify DOM event listener behavior.

```html
<div data-controller="gallery"
     data-action="scroll->gallery#layout:!passive">
  <img data-action="click->gallery#open:capture">
</div>
```

--------------------------------

### Refactor Hello Controller with Name Getter

Source: https://stimulus.hotwired.dev/handbook/hello-stimulus

This refactored JavaScript controller uses a 'name' getter to access the input target's value, simplifying the 'greet' method.

```javascript
// src/controllers/hello_controller.js
import { Controller } from "@hotwired/stimulus"

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

  greet() {
    console.log(`Hello, ${this.name}!")
  }

  get name() {
    return this.nameTarget.value
  }
}
```

--------------------------------

### Multiple Elements with the Same Controller

Source: https://stimulus.hotwired.dev/reference/controllers

Illustrates how multiple HTML elements can each have their own instance of the same Stimulus controller.

```html
<ul>
  <li data-controller="list-item">One</li>
  <li data-controller="list-item">Two</li>
  <li data-controller="list-item">Three</li>
</ul>
```

--------------------------------

### Define Action Method in Stimulus Controller

Source: https://stimulus.hotwired.dev/handbook/hello-stimulus

Renames the 'connect' method to 'greet' to serve as an action method for handling user interactions.

```javascript
// src/controllers/hello_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  greet() {
    console.log("Hello, Stimulus!", this.element)
  }
}
```

--------------------------------

### Global Event Listener on Window

Source: https://stimulus.hotwired.dev/reference/actions

Attaches a 'resize' event listener to the global 'window' object, triggering the 'layout' method of the 'gallery' controller.

```html
<div data-controller="gallery"
     data-action="resize@window->gallery#layout">
</div>
```

--------------------------------

### Action Shorthand for Common Events

Source: https://stimulus.hotwired.dev/reference/actions

Uses shorthand for a 'click' event on a button, directly mapping to the 'gallery#next' method.

```html
<button data-action="gallery#next">…</button>
```

--------------------------------

### Multiple Controllers on an Element

Source: https://stimulus.hotwired.dev/reference/controllers

Shows how to attach multiple Stimulus controllers to a single HTML element using a space-separated list of identifiers.

```html
<div data-controller="clipboard list-item"></div>
```

--------------------------------

### Stimulus Clipboard Controller with Link Action

Source: https://stimulus.hotwired.dev/handbook/building-something-real

Use any element with a data-action attribute for Stimulus controllers. Clicking the link will trigger the copy action.

```html
<div data-controller="clipboard">
  PIN: <input data-clipboard-target="source" type="text" value="3737" readonly>
  <a href="#" data-action="clipboard#copy">Copy to Clipboard</a>
</div>
```

--------------------------------

### Nested Controller Scopes

Source: https://stimulus.hotwired.dev/reference/controllers

Demonstrates how nested controllers have their own scopes, and parent controllers are unaware of targets within nested scopes.

```html
<ul id="parent" data-controller="list">
  <li data-list-target="item">One</li>
  <li data-list-target="item">Two</li>
  <li>
    <ul id="child" data-controller="list">
      <li data-list-target="item">I am</li>
      <li data-list-target="item">a nested list</li>
    </ul>
  </li>
</ul>
```

--------------------------------

### Implement Clipboard Copy Logic

Source: https://stimulus.hotwired.dev/handbook/building-something-real

This method selects the value from the 'source' target input field and writes it to the system clipboard using the navigator.clipboard.writeText() API.

```javascript
copy() {
    navigator.clipboard.writeText(this.sourceTarget.value)
  }
```

--------------------------------

### Stimulus Controller Using Action Parameters for URL

Source: https://stimulus.hotwired.dev/handbook/working-with-external-resources

A Stimulus controller that accepts a URL parameter via its action to fetch and display content.

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

export default class extends Controller {
  load({ params }) {
    fetch(params.url)
      .then(response => response.text())
      .then(html => this.element.innerHTML = html)
  }
}
```

--------------------------------

### Accessing Optional Outlets

Source: https://stimulus.hotwired.dev/reference/outlets

Use the existential property (e.g., `hasUserStatusOutlet`) to safely access optional outlets and avoid errors if they are not present.

```javascript
if (this.hasUserStatusOutlet) {
  this.userStatusOutlet.safelyCallSomethingOnTheOutlet()
}
```

--------------------------------

### Connect Stimulus Controller to HTML

Source: https://stimulus.hotwired.dev/handbook/building-something-real

Add the 'data-controller="clipboard"' attribute to an HTML element to connect an instance of the Stimulus clipboard controller to that element and its descendants.

```html
<div data-controller="clipboard">

```

--------------------------------

### HTML Structure for Copy Button

Source: https://stimulus.hotwired.dev/handbook/building-something-real

This HTML sets up a PIN input field and a button to trigger the copy action. The input is marked as read-only.

```html
<div>
  PIN: <input type="text" value="1234" readonly>
  <button>Copy to Clipboard</button>
</div>
```

--------------------------------

### Target Naming Conventions (Camel Case)

Source: https://stimulus.hotwired.dev/reference/targets

Illustrates the correct use of camelCase for target names in HTML attributes and their corresponding declaration in the Stimulus controller's `static targets` array.

```html
<span data-search-target="camelCase"></span>
<span data-search-target="do-not-do-this"></span>
```

```javascript
export default class extends Controller {
  static targets = [ "camelCase" ]  
}
```

--------------------------------

### HTML Structure with Stimulus Attributes

Source: https://stimulus.hotwired.dev/

This HTML snippet demonstrates how to use Stimulus data attributes to define a controller, targets, and actions.

```html
<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>
```

--------------------------------

### Destructuring Parameters in Stimulus Actions

Source: https://stimulus.hotwired.dev/reference/actions

Illustrates how to destructure all parameters directly within the action method signature or destructure only specific parameters needed.

```javascript
upvote({ params }) {
  // { id: 12345, url: "/votes", active: true, payload: { value: 1234567 } }
  console.log(params)
}
```

```javascript
upvote({ params: { id, url } }) {
  console.log(id) // 12345
  console.log(url) // "/votes"
}
```

--------------------------------

### Map logical class names to HTML attributes

Source: https://stimulus.hotwired.dev/reference/css-classes

Associate the logical 'loading' class with the actual CSS class 'search--busy' using a data attribute. This element also has the Stimulus controller.

```html
<form data-controller="search"
      data-search-loading-class="search--busy">
  <input data-action="search#loadResults">
</form>

```

--------------------------------

### Stimulus Controller: Connect method with Clipboard API check

Source: https://stimulus.hotwired.dev/handbook/designing-for-resilience

This method tests for Clipboard API support and adds the 'supported' class to the element if available. Access the class name via `this.supportedClass`.

```javascript
  connect() {
    if ("clipboard" in navigator) {
      this.element.classList.add(this.supportedClass);
    }
  }

```

--------------------------------

### Defining Targets in Controller

Source: https://stimulus.hotwired.dev/reference/targets

Shows how to declare target names ('query', 'errorMessage', 'results') within a Stimulus controller class using the `static targets` array.

```javascript
// controllers/search_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = [ "query", "errorMessage", "results" ]
  // …
}
```

--------------------------------

### Trigger Behavior After Controller Registration

Source: https://stimulus.hotwired.dev/reference/controllers

Implement the static `afterLoad` method to execute code immediately after a controller is registered, even before the DOM is ready.

```javascript
class SpinnerButton extends Controller {
  static legacySelector = ".legacy-spinner-button"

  static afterLoad(identifier, application) {
    // use the application instance to read the configured 'data-controller' attribute
    const { controllerAttribute } = application.schema

    // update any legacy buttons with the controller's registered identifier
    const updateLegacySpinners = () => {
      document.querySelector(this.legacySelector).forEach((element) => {
        element.setAttribute(controllerAttribute, identifier)
      })
    }

    // called as soon as registered so DOM may not have loaded yet
    if (document.readyState == "loading") {
      document.addEventListener("DOMContentLoaded", updateLegacySpinners)
    } else {
      updateLegacySpinners()
    }
  }
}

// This controller will update any legacy spinner buttons to use the controller
application.register("spinner-button", SpinnerButton)
```

--------------------------------

### Accessing Parameters in Stimulus Action Methods

Source: https://stimulus.hotwired.dev/reference/actions

Shows how to access parameters passed to a Stimulus action method via `event.params`. Parameters are automatically typecast.

```javascript
// ItemController
upvote(event) {
  // { id: 12345, url: "/votes", active: true, payload: { value: 1234567 } }
  console.log(event.params)
}

// SpinnerController
start(event) {
  // {}
  console.log(event.params)
}
```

--------------------------------

### Stimulus Controller for Actions

Source: https://stimulus.hotwired.dev/reference/actions

Defines the 'gallery' controller with a 'next' method to handle the 'click' event.

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

export default class extends Controller {
  next(event) {
    // …
  }
}
```

--------------------------------

### Shared Targets Across Multiple Controllers

Source: https://stimulus.hotwired.dev/reference/targets

Demonstrates how HTML elements can be targets for multiple Stimulus controllers simultaneously by including multiple `data-controller` attributes on a parent element and distinct `data-target` attributes for each controller.

```html
<form data-controller="search checkbox">
  <input type="checkbox" data-search-target="projects" data-checkbox-target="input">
  <input type="checkbox" data-search-target="messages" data-checkbox-target="input">
  …
</form>
```

--------------------------------

### Connect Button Action to Controller Method

Source: https://stimulus.hotwired.dev/handbook/building-something-real

Add 'data-action="clipboard#copy"' to a button to trigger the 'copy()' method of the Stimulus clipboard controller when the button is clicked. 'click->' is omitted as 'click' is the default event for buttons.

```html
<button data-action="clipboard#copy">Copy to Clipboard</button>
```

--------------------------------

### Basic Target Element Structure

Source: https://stimulus.hotwired.dev/reference/targets

This HTML structure demonstrates how to define elements as targets for a Stimulus controller using the `data-controller` and `data-[controller-name]-target` attributes.

```html
<div data-controller="search">
  <input type="text" data-search-target="query">
  <div data-search-target="errorMessage"></div>
  <div data-search-target="results"></div>
</div>
```

--------------------------------

### CSS: Hide button by default, show when supported

Source: https://stimulus.hotwired.dev/handbook/designing-for-resilience

Styles to hide the button initially and reveal it when the 'clipboard--supported' class is present on a parent element.

```css
.clipboard-button {
  display: none;
}

.clipboard--supported .clipboard-button {
  display: initial;
}

```

--------------------------------

### Connect Action Method to DOM Event

Source: https://stimulus.hotwired.dev/handbook/hello-stimulus

Attaches a Stimulus action method ('greet') to a button's 'click' event using the 'data-action' attribute.

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

--------------------------------

### Link Controller to HTML with Data-Controller

Source: https://stimulus.hotwired.dev/handbook/hello-stimulus

Associates a Stimulus controller with an HTML element by setting the 'data-controller' attribute.

```html
<div data-controller="hello">
  <input type="text">
  <button>Greet</button>
</div>
```

--------------------------------

### Apply multiple CSS classes using plural property

Source: https://stimulus.hotwired.dev/reference/css-classes

Utilize the plural `this.loadingClasses` property and spread syntax to add all mapped CSS classes to the controller's element. This is useful when a logical name represents several distinct styles.

```javascript
export default class extends Controller {
  static classes = [ "loading" ]

  loadResults() {
    this.element.classList.add(...this.loadingClasses)

    fetch(/* … */)
  }
}

```

--------------------------------

### Avoid Repeating Event Names in Actions

Source: https://stimulus.hotwired.dev/reference/actions

Do not use action names that simply repeat the event's name. Use descriptive names based on the intended behavior.

```html
<button data-action="click->profile#click">Don't</button>
```

```html
<button data-action="click->profile#showDialog">Do</button>
```

--------------------------------

### Stimulus Controller Implementation

Source: https://stimulus.hotwired.dev/

This JavaScript code defines a Stimulus controller that responds to user interactions and updates the DOM based on defined targets.

```javascript
import { Controller } from "stimulus"

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

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

--------------------------------

### Outlet Attribute Syntax

Source: https://stimulus.hotwired.dev/reference/outlets

Defines the syntax for an outlet attribute, specifying the controller identifier and the CSS selector for the outlet.

```html
data-[identifier]-[outlet]-outlet="[selector]"
```

--------------------------------

### Missing Outlet Exception

Source: https://stimulus.hotwired.dev/reference/outlets

Stimulus throws an exception if a declared outlet is not found. Ensure the outlet element exists and is correctly configured.

```text
Missing outlet element "user-status" for "chat" controller
```

--------------------------------

### Inline Controller Registration

Source: https://stimulus.hotwired.dev/reference/controllers

Registers a controller class inline without needing a separate import, useful for simple or anonymous controllers.

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

application.register("reference", class extends Controller {
  // …
})
```

--------------------------------

### Basic HTML Structure for Stimulus

Source: https://stimulus.hotwired.dev/handbook/hello-stimulus

Initial HTML markup to be added to the body of an HTML file for Stimulus integration.

```html
<div>
  <input type="text">
  <button>Greet</button>
</div>
```

--------------------------------

### Basic Controller Structure

Source: https://stimulus.hotwired.dev/reference/controllers

Defines the fundamental structure of a Stimulus controller class, inheriting from the base Controller class.

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

export default class extends Controller {
  // …
}
```

--------------------------------

### Map multiple CSS classes to a logical name

Source: https://stimulus.hotwired.dev/reference/css-classes

Specify multiple CSS classes for a single logical name by separating them with spaces in the data attribute. This allows for complex styling combinations.

```html
<form data-controller="search"
      data-search-loading-class="bg-gray-500 animate-spinner cursor-busy">
  <input data-action="search#loadResults">
</form>

```

--------------------------------

### Log Message on Controller Connection

Source: https://stimulus.hotwired.dev/handbook/hello-stimulus

Implements the 'connect' method in a Stimulus controller to log a message and the controller's element when it connects to the DOM.

```javascript
// src/controllers/hello_controller.js
import { Controller } from "@hotwired/stimulus"

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

--------------------------------

### Define Values in a Controller

Source: https://stimulus.hotwired.dev/reference/values

Define values in a controller using the `static values` object. Put each value’s name on the left and its type on the right.

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

export default class extends Controller {
  static values = {
    url: String
  }

  connect() {
    fetch(this.urlValue).then(/* … */)
  }
}
```

```javascript
export default class extends Controller {
  static values = {
    url: String,
    interval: Number,
    params: Object
  }

  // …
}
```

--------------------------------

### Define Multiple Values with Defaults

Source: https://stimulus.hotwired.dev/handbook/managing-state

Define multiple values in a Stimulus controller, specifying types and defaults for some properties. This allows for flexible configuration of controller state.

```javascript
static values = { index: Number, effect: { type: String, default: "kenburns" } }
```

--------------------------------

### Log Stimulus Value and Type

Source: https://stimulus.hotwired.dev/handbook/managing-state

Access and log the typed value of a Stimulus controller property. This demonstrates the automatic type conversion provided by Stimulus values.

```javascript
export default class extends Controller {
  static values = { index: Number }

  initialize() {
    console.log(this.indexValue)
    console.log(typeof this.indexValue)
  }

  // …
}
```

--------------------------------

### Stopping Action Chain with stopImmediatePropagation

Source: https://stimulus.hotwired.dev/reference/actions

Demonstrates how to use event.stopImmediatePropagation() within an action method to prevent subsequent actions in the chain from being invoked.

```javascript
highlight(event) {
  event.stopImmediatePropagation()
  // ...
}
```

--------------------------------

### HTML Data Attribute for Value

Source: https://stimulus.hotwired.dev/reference/values

Place data attributes for values on the same element as the `data-controller` attribute.

```html
<div data-controller="loader" data-loader-url-value="/messages">
</div>
```

--------------------------------

### Define logical CSS classes in a Stimulus controller

Source: https://stimulus.hotwired.dev/reference/css-classes

Declare the logical names for CSS classes your controller will use. Stimulus maps these to data attributes.

```javascript
// controllers/search_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static classes = [ "loading" ]

  // …
}

```

--------------------------------

### Manual Controller Registration

Source: https://stimulus.hotwired.dev/reference/controllers

Registers a controller class with a specific identifier using the Application#register method.

```javascript
import ReferenceController from "./controllers/reference_controller"

application.register("reference", ReferenceController)
```

--------------------------------

### Define Target for Clipboard Controller

Source: https://stimulus.hotwired.dev/handbook/building-something-real

Use 'data-clipboard-target="source"' on an input element to designate it as the 'source' target for the Stimulus clipboard controller. This allows the controller to access the element.

```html
PIN: <input data-clipboard-target="source" type="text" value="1234" readonly>
```

--------------------------------

### Directly Invoke Other Controller Method

Source: https://stimulus.hotwired.dev/reference/controllers

Use `getControllerForElementAndIdentifier` to access another controller instance and call its methods. This approach should be reserved for unique scenarios where event-based communication is not practical.

```javascript
class MyController extends Controller {
  static targets = [ "other" ]

  copy() {
    const otherController = this.application.getControllerForElementAndIdentifier(this.otherTarget, 'other')
    otherController.otherMethod()
  }
}
```

--------------------------------

### Auto-refresh HTML content with a timer

Source: https://stimulus.hotwired.dev/handbook/working-with-external-resources

Enhance the content loader to periodically refresh its content. Set the refresh interval in milliseconds using `data-content-loader-refresh-interval-value`.

```html
<div data-controller="content-loader"
     data-content-loader-url-value="/messages.html"
     data-content-loader-refresh-interval-value="5000"></div>
```

```javascript
export default class extends Controller {
  static values = { url: String, refreshInterval: Number }

  startRefreshing() {
    setInterval(() => {
      this.load()
    }, this.refreshIntervalValue)
  }

  // …
}
```

```javascript
  connect() {
    this.load()

    if (this.hasRefreshIntervalValue) {
      this.startRefreshing()
    }
  }
```

--------------------------------

### Apply a single CSS class using controller property

Source: https://stimulus.hotwired.dev/reference/css-classes

Use the singular `this.loadingClass` property to add the mapped CSS class to the controller's element. This is typically done within an action method.

```javascript
export default class extends Controller {
  static classes = [ "loading" ]

  loadResults() {
    this.element.classList.add(this.loadingClass)

    fetch(/* … */)
  }
}

```

--------------------------------

### Stimulus Controller with Values and Targets

Source: https://stimulus.hotwired.dev/handbook/managing-state

A Stimulus controller managing slide visibility based on an index value, utilizing targets for slide elements. The index value is incremented/decremented and used to show the current slide.

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

export default class extends Controller {
  static targets = [ "slide" ]
  static values = { index: Number }

  initialize() {
    this.showCurrentSlide()
  }

  next() {
    this.indexValue++
    this.showCurrentSlide()
  }

  previous() {
    this.indexValue--
    this.showCurrentSlide()
  }

  showCurrentSlide() {
    this.slideTargets.forEach((element, index) => {
      element.hidden = index !== this.indexValue
    })
  }
}
```

--------------------------------

### Dispatching Events Across Window Scope

Source: https://stimulus.hotwired.dev/reference/controllers

When controllers are not in a parent-child relationship, append `@window` to the `data-action` attribute to dispatch events across the entire window.

```html
<div data-action="clipboard:copy@window->effects#flash">
</div>
```

--------------------------------

### HTML: Add data-clipboard-supported-class attribute

Source: https://stimulus.hotwired.dev/handbook/designing-for-resilience

Add this attribute to the Stimulus controller element to specify a CSS class that will be added when the feature is supported.

```html
  <div data-controller="clipboard" data-clipboard-supported-class="clipboard--supported">

```

--------------------------------

### Stimulus Controller Destructuring URL Parameter

Source: https://stimulus.hotwired.dev/handbook/working-with-external-resources

A more concise version of the `load` action that directly destructures the `url` parameter from the action event.

```javascript
  load({ params: { url } }) {
    fetch(url)
      .then(response => response.text())
      .then(html => this.element.innerHTML = html)
  }
```

--------------------------------

### HTML Structure for Slideshow Controller

Source: https://stimulus.hotwired.dev/handbook/managing-state

Defines the HTML elements for a slideshow, including buttons for navigation and elements marked as slide targets.

```html
<div data-controller="slideshow">
  <button data-action="slideshow#previous"> ← </button>
  <button data-action="slideshow#next"> → </button>

  <div data-slideshow-target="slide">🐵</div>
  <div data-slideshow-target="slide">🙈</div>
  <div data-slideshow-target="slide">🙉</div>
  <div data-slideshow-target="slide">🙊</div>
</div>
```

--------------------------------

### Stimulus Controller: Define static classes

Source: https://stimulus.hotwired.dev/handbook/designing-for-resilience

Declare static classes that will be used to control CSS class names applied to the controller's element.

```javascript
  static classes = [ "supported" ]

```

--------------------------------

### Stimulus Clipboard Target with Textarea

Source: https://stimulus.hotwired.dev/handbook/building-something-real

Stimulus targets can be any element with the expected properties. A textarea can be used as a source target if it has a 'value' property.

```html
PIN: <textarea data-clipboard-target="source" readonly>3737</textarea>
```

--------------------------------

### Stimulus Slideshow Controller Logic

Source: https://stimulus.hotwired.dev/handbook/managing-state

Implements a Stimulus controller to manage a slideshow. It tracks the current slide index and updates the visibility of slide elements.

```javascript
// src/controllers/slideshow_controller.js
import { Controller } from "@hotwired/stimulus"

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

  initialize() {
    this.index = 0
    this.showCurrentSlide()
  }

  next() {
    this.index++
    this.showCurrentSlide()
  }

  previous() {
    this.index--
    this.showCurrentSlide()
  }

  showCurrentSlide() {
    this.slideTargets.forEach((element, index) => {
      element.hidden = index !== this.index
    })
  }
}
```

--------------------------------

### Prevent Controller Loading

Source: https://stimulus.hotwired.dev/reference/controllers

Overwrite the static `shouldLoad` method to conditionally register a controller based on environmental factors like user agent.

```javascript
class UnloadableController extends ApplicationController {
  static get shouldLoad() {
    return false
  }
}

// This controller will not be loaded
application.register("unloadable", UnloadableController)
```

--------------------------------

### HTML: Add class to the button element

Source: https://stimulus.hotwired.dev/handbook/designing-for-resilience

Apply this class to the button that should be conditionally displayed based on feature support.

```html
  <button data-action="clipboard#copy" class="clipboard-button">Copy to Clipboard</button>

```

--------------------------------

### Target Element Connection and Disconnection Callbacks

Source: https://stimulus.hotwired.dev/reference/targets

Defines `itemTargetConnected` and `itemTargetDisconnected` methods to respond to the addition or removal of elements matching the 'item' target name within the controller's scope.

```javascript
export default class extends Controller {
  static targets = [ "item" ]

  itemTargetConnected(element) {
    this.sortElements(this.itemTargets)
  }

  itemTargetDisconnected(element) {
    this.sortElements(this.itemTargets)
  }

  // Private
  sortElements(itemTargets) { /* ... */ }
}
```

--------------------------------

### Declare Target in Stimulus Controller

Source: https://stimulus.hotwired.dev/handbook/building-something-real

Declare 'static targets = [ "source" ]' within your Stimulus controller class to enable access to elements marked with 'data-clipboard-target="source"'. Stimulus provides 'this.sourceTarget', 'this.sourceTargets', and 'this.hasSourceTarget'.

```javascript
export default class extends Controller {
  static targets = [ "source" ]

  // ...
}
```

--------------------------------

### Dispatching Cross-Controller Events

Source: https://stimulus.hotwired.dev/reference/controllers

Use the `dispatch` method within a controller to send custom events, which can be listened to by other controllers via `data-action` attributes.

```javascript
class ClipboardController extends Controller {
  static targets = [ "source" ]

  copy() {
    this.dispatch("copy", { detail: { content: this.sourceTarget.value } })
    navigator.clipboard.writeText(this.sourceTarget.value)
  }
}
```

```html
<div data-controller="clipboard effects" data-action="clipboard:copy->effects#flash">
  PIN: <input data-clipboard-target="source" type="text" value="1234" readonly>
  <button data-action="clipboard#copy">Copy to Clipboard</button>
</div>
```

```javascript
class EffectsController extends Controller {
  flash({ detail: { content } }) {
    console.log(content) // 1234
  }
}
```

--------------------------------

### Define Custom Controller Properties

Source: https://stimulus.hotwired.dev/reference/using-typescript

Define custom properties on a Stimulus controller class using standard TypeScript syntax. This allows for adding any necessary properties to the controller instance.

```typescript
import { Controller } from "@hotwired/stimulus"

export default class MyController extends Controller {
  container: HTMLElement
}
```

--------------------------------

### Stimulus Controller with Value Change Callback

Source: https://stimulus.hotwired.dev/handbook/managing-state

Refactored Stimulus controller using a value change callback (`indexValueChanged`) to automatically update the UI when the index value changes. This eliminates manual calls to `showCurrentSlide` in action methods.

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

export default class extends Controller {
  static targets = [ "slide" ]
  static values = { index: Number }

  next() {
    this.indexValue++
  }

  previous() {
    this.indexValue--
  }

  indexValueChanged() {
    this.showCurrentSlide()
  }

  showCurrentSlide() {
    this.slideTargets.forEach((element, index) => {
      element.hidden = index !== this.indexValue
    })
  }
}
```

--------------------------------

### HTML Element with Controller Identifier

Source: https://stimulus.hotwired.dev/reference/controllers

Associates a Stimulus controller with an HTML element using the data-controller attribute.

```html
<div data-controller="reference"></div>
```

--------------------------------

### Referencing Non-Controller Elements Exception

Source: https://stimulus.hotwired.dev/reference/outlets

An exception is thrown if an element declared as an outlet lacks a corresponding `data-controller` attribute and identifier. Ensure all outlet elements are properly associated with a Stimulus controller.

```html
<div data-controller="chat" data-chat-user-status-outlet="#user-column"></div>

<div id="user-column"></div>
```

```text
Missing "data-controller=user-status" attribute on outlet element for
"chat" controller
```

--------------------------------

### Outlet Connection and Disconnection Callbacks

Source: https://stimulus.hotwired.dev/reference/outlets

Defines specially named functions that Stimulus calls when an outlet is added (`userStatusOutletConnected`) or removed (`userStatusOutletDisconnected`) from the page.

```javascript
// chat_controller.js

export default class extends Controller {
  static outlets = [ "user-status" ]

  userStatusOutletConnected(outlet, element) {
    // ...
  }

  userStatusOutletDisconnected(outlet, element) {
    // ...
  }
}
```

--------------------------------

### Dispatching Cancellable Events

Source: https://stimulus.hotwired.dev/reference/controllers

Make dispatched events cancellable by setting `cancelable: true` in the `dispatch` options. The receiving controller can then call `event.preventDefault()` to stop the default behavior.

```javascript
class ClipboardController extends Controller {
  static targets = [ "source" ]

  copy() {
    const event = this.dispatch("copy", { cancelable: true })
    if (event.defaultPrevented) return
    navigator.clipboard.writeText(this.sourceTarget.value)
  }
}
```

```javascript
class EffectsController extends Controller {
  flash(event) {
    // this will prevent the default behaviour as determined by the dispatched event
    event.preventDefault()
  }
}
```

--------------------------------

### Custom Stimulus Error Handling

Source: https://stimulus.hotwired.dev/handbook/installing

Override the default error handling behavior of Stimulus by defining the Application#handleError method.

```javascript
// src/application.js
import { Application } from "@hotwired/stimulus"
window.Stimulus = Application.start()

Stimulus.handleError = (error, message, detail) => {
  console.warn(message, detail)
  ErrorTrackingSystem.captureException(error)
}
```

--------------------------------

### Compound Keyboard Event Filter with Modifier Key

Source: https://stimulus.hotwired.dev/reference/actions

Listens for the 'Ctrl+A' key combination to trigger the 'selectAll' method of the 'listbox' controller.

```html
<div data-action="keydown.ctrl+a->listbox#selectAll" role="option" tabindex="0">...</div>
```

--------------------------------

### Define Default Values for Stimulus Values

Source: https://stimulus.hotwired.dev/reference/values

Specify default values in the controller definition for values that have not been specified on the controller element. The expanded form of `{ type, default }` can be mixed with the regular form.

```javascript
export default class extends Controller {
  static values = {
    url: { type: String, default: '/bill' },
    interval: { type: Number, default: 5 },
    clicked: Boolean
  }
}
```

--------------------------------

### Define a CSS class for a busy state

Source: https://stimulus.hotwired.dev/reference/css-classes

This CSS rule defines the visual appearance of the 'search--busy' class, typically used to show a loading indicator.

```css
.search--busy {
  background-image: url(throbber.svg) no-repeat;
}

```

--------------------------------

### Define Target Properties with TypeScript

Source: https://stimulus.hotwired.dev/reference/using-typescript

Define the TypeScript types for Stimulus controller targets using the `declare` keyword. This allows TypeScript to correctly infer the types of target elements, such as `HTMLInputElement` for an input target.

```typescript
import { Controller } from "@hotwired/stimulus"

export default class MyController extends Controller {
  static targets = [ "input" ]

  declare readonly hasInputTarget: boolean
  declare readonly inputTarget: HTMLInputElement
  declare readonly inputTargets: HTMLInputElement[]
}
```

--------------------------------

### HTML with Data Attribute for Stimulus Value

Source: https://stimulus.hotwired.dev/handbook/managing-state

Associate a data attribute with a Stimulus controller's value. The attribute name is derived from the controller name and the value name.

```html
<div data-controller="slideshow" data-slideshow-index-value="1">
```
Tokens:
Raw