Values

You can read and write HTML data attributes on controller elements as typed values using special controller properties.

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

// controllers/loader_controller.js
import { Controller } from "stimulus"

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

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

﹟ Definitions

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

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

  // …
}

﹟ Types

A value’s type is one of Array, Boolean, Number, Object, or String. The type determines how the value is transcoded between JavaScript and HTML.

﹟ Properties and Attributes

Stimulus automatically generates getter, setter, and existential properties for each value defined in a controller. These properties are linked to data attributes on the controller’s element:

﹟ Getters

The getter for a value decodes the associated data attribute into an instance of the value’s type.

If the data attribute is missing from the controller’s element, the getter returns a default value, depending on the value’s type:

﹟ Setters

The setter for a value sets the associated data attribute on the controller’s element.

To remove the data attribute from the controller’s element, assign undefined to the value.

﹟ Existential Properties

The existential property for a value evaluates to true when the associated data attribute is present on the controller’s element and false when it is absent.

﹟ Change Callbacks

Value change callbacks let you respond whenever a value’s data attribute changes.

Define a method [name]ValueChanged in the controller, where [name] is the name of the value you want to observe for changes. The method receives its decoded value as the first argument.

Stimulus invokes each change callback after the controller is initialized and again any time its associated data attribute changes. This includes changes as a result of assignment to the value’s setter.

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

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

﹟ Naming Conventions

Write value names as camelCase in JavaScript and kebab-case in HTML. For example, a value named contentType in the loader controller will have the associated data attribute data-loader-content-type-value.

Next: CSS Classes