Stimulus

https://stimulus.hotwired.dev/handbook/
Admin
Stimulus is a modest JavaScript framework designed to enhance static or server-rendered HTML by...
Tokens:7,342
Snippets:105
Trust Score:9.3
Update:2 months 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">

```

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

### 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)
    }
  }
}
```

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

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

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

### 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)
  }
```

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

### 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()
}
```

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

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

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

### 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 {
}
```

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

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

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

### 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() {
  }
}
```

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

### 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)
  }
}
```

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

### 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)
```

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

### 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))
```

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

### 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
  }
}
```

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

### 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)
  }
}
```

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

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

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

### 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)
  }
}
```

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

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

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

### 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);
    }
  }

```

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

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

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

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

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

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

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

### 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 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)
  }

  // …
}
```

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

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

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

### 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()
    }
  }
```

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

### 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
    })
  }
}
```

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

### 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
    })
  }
}
```

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

### 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>

```

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

### 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" ]

  // ...
}
```

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

### 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
    })
  }
}
```

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

### 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)
}
```

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

### 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">
```

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

### Define Numeric Value in Stimulus Controller

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

Define a numeric value property in a Stimulus controller. Stimulus automatically maps this to a data attribute and handles type conversion.

```javascript
static values = { index: Number }
```

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

### Override Stimulus Default Attributes

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

Customize Stimulus's core data attributes like 'data-controller' or 'data-action' when initializing the Application instance.

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

const customSchema = {
  ...defaultSchema,
  actionAttribute: 'data-stimulus-action'
}

window.Stimulus = Application.start(document.documentElement, customSchema);
```

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

### Stimulus Copy Action with PreventDefault

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

Cancel the default browser behavior for an action by calling event.preventDefault() within the action method. This is useful for link elements.

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

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

### Disconnect Stimulus Controller and Stop Timer

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

Calls `stopRefreshing` when the controller disconnects from the DOM, preventing background requests.

```javascript
disconnect() {
    this.stopRefreshing()
  }
```

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

### Set Default Value in Stimulus Controller

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

Define a default value for a Stimulus controller property. This default is used if the corresponding data attribute is not present on the controller element.

```javascript
static values = { index: { type: Number, default: 2 } }
```

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

### Stop Refresh Timer in Stimulus Controller

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

Clears the interval timer to prevent further calls to `load`. This should be called when the controller disconnects.

```javascript
stopRefreshing() {
    if (this.refreshTimer) {
      clearInterval(this.refreshTimer)
    }
  }
```
Tokens:
Raw