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="search">
<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.