Skip to content

Targets

Targets let you reference important elements by name.

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

Attributes and Names

The data-search-target attribute is called a target attribute, and its value is a space-separated list of target names which you can use to refer to the element in the search controller.

<div data-controller="s​earch">
  <div data-search-target="results"></div>
</div>

Definitions

Define target names in your controller class using the static targets array:

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

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

Properties

For each target name defined in the static targets array, Stimulus adds the following properties to your controller, where [name] corresponds to the target’s name:

Kind Name Value
Singular this.[name]Target The first matching target in scope
Plural this.[name]Targets An array of all matching targets in scope
Existential this.has[Name]Target A boolean indicating whether there is a matching target in scope


Note: Accessing the singular target property will throw an error when there is no matching element.

Shared Targets

Elements can have more than one target attribute, and it’s common for targets to be shared by multiple controllers.

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

In the example above, the checkboxes are accessible inside the search controller as this.projectsTarget and this.messagesTarget, respectively.

Inside the checkbox controller, this.inputTargets returns an array with both checkboxes.

Optional Targets

If your controller needs to work with a target which may or may not be present, condition your code based on the value of the existential target property:

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

Naming Conventions

Always use camelCase to specify target names, since they map directly to properties on your controller.

Next: Values