CSS Classes

In HTML, a CSS class defines a set of styles which can be applied to elements using the class attribute.

CSS classes are a convenient tool for changing styles and playing animations programmatically. For example, a Stimulus controller might add a “loading” class to an element when it is performing an operation in the background, and then style that class in CSS to display a progress indicator:

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

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

As an alternative to hard-coding classes with JavaScript strings, Stimulus lets you refer to CSS classes by logical name using a combination of data attributes and controller properties.

﹟Definitions

Define CSS classes by logical name in your controller using the static classes array:

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

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

  // …
}

﹟Attributes

The logical names defined in the controller’s static classes array map to CSS class attributes on the controller’s element.

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

Construct a CSS class attribute by joining together the controller identifier and logical name in the format data-[identifier]-[logical-name]-class. The attribute’s value is a single CSS class name.

Note: CSS class attributes must be specified on the same element as the data-controller attribute.

﹟Properties

For each logical name defined in the static classes array, Stimulus adds the following CSS class properties to your controller:

Use these properties to apply CSS classes to elements with the add() and remove() methods of the DOM classList API.

For example, to display a loading indicator on the search controller’s element before fetching results, you might implement the loadResults action like so:

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

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

    fetch(/* … */)
  }
}

Note: Stimulus will throw an error if you attempt to access a CSS class property when no matching CSS class attribute is present.

﹟Naming Conventions

Use camelCase to specify logical names in CSS class definitions. Logical names map to camelCase CSS class properties:

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

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

In HTML, write CSS class attributes in kebab-case:

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

When constructing CSS class attributes, follow the conventions for identifiers as described in Controllers: Naming Conventions.