skip to content

In Stimulus, how does static outlets with a data-question-navigator-countdown-outlet selector give one controller another controller's instance, and when do outlet callbacks fire?

level: middleimportance: should knowfreq 35%

answer

  1. outlet name = the other identifier
  2. selector attribute on the host element
  3. matched anywhere in the page
  4. countdownOutlet throws, hasCountdownOutlet doesn't
  5. countdownOutletConnected(outlet, element)

basics

~20 s

The host declares static outlets = ["countdown"] and puts a CSS selector in data-question-navigator-countdown-outlet; any element in the page matching it and carrying data-controller="countdown" becomes an outlet, reachable as this.countdownOutlet (the controller instance), with countdownOutletConnected/Disconnected callbacks.

solid answer

~40 s

An outlet is a reference from a host controller to other controller instances, found by selector. The question navigator declares `static outlets = ["countdown"]`, where the name must equal the other controller's identifier, and its element carries `data-question-navigator-countdown-outlet="#exam-countdown"`. Stimulus searches the whole document, not just the host's subtree, for elements that match the selector and also carry `data-controller="countdown"`. It generates `this.countdownOutlet` (the first controller instance, throwing if none), `countdownOutlets`, `countdownOutletElement`, `countdownOutletElements` and `hasCountdownOutlet`. The host can then call `this.countdownOutlet.pause()` or read its values. `countdownOutletConnected(outlet, element)` and `countdownOutletDisconnected(...)` fire as matching controllers appear and disappear, for instance when a Turbo Frame loads the timer later.

code

html · 12 lines
html
<header>
  <div id="exam-countdown" data-controller="countdown"
       data-countdown-seconds-value="1800">
    <span data-countdown-target="display"></span>
  </div>
</header>

<nav data-controller="question-navigator"
     data-question-navigator-countdown-outlet="#exam-countdown">
  <button type="button" data-action="question-navigator#review"
          disabled data-question-navigator-target="review">Review flagged</button>
</nav>

go deeper

for a junior

Recall that outlets let one controller reach another, declared in static outlets and wired with a selector attribute on the host.

for a middle

Explain the name rule, the document-wide selector match with the data-controller check, the five properties and the connected and disconnected callbacks.

for a senior

Handle outlets that appear late or vanish through Turbo, guard optional ones, and keep the coupling deliberate and narrow.

for a principal

Decide where direct controller-to-controller calls are acceptable and keep a page's outlet graph shallow enough to reason about.

## What an outlet is **Targets** reference elements inside a controller. **Outlets** reference **other controllers**: their instances and their elements, anywhere on the page. In the exam-practice app, the `question-navigator` controller sits in a sidebar while the `countdown` controller sits in the page header; neither contains the other, and the navigator needs to pause the clock while the candidate reviews flagged questions. ## Wiring one up 1. The host declares the outlet by the other controller's identifier: `static outlets = ["countdown"]`. 2. The host's element carries a CSS selector in `data-<host>-<outlet>-outlet`: `data-question-navigator-countdown-outlet="#exam-countdown"`. 3. The outlet element matches that selector **and** has `countdown` in its `data-controller`. An element that matches the selector without the identifier is not an outlet. The selector is evaluated against the whole document, so outlets work across distant parts of the layout. A loose selector such as `.timer` that matches several countdowns yields several outlets, and the singular property quietly returns the first. ## The generated properties | property | returns | |---|---| | `this.countdownOutlet` | the first outlet's controller instance; throws if no matching element exists | | `this.countdownOutlets` | an array of controller instances | | `this.countdownOutletElement` | the first outlet's element; throws if none | | `this.countdownOutletElements` | an array of elements | | `this.hasCountdownOutlet` | whether a matching element exists | Because you get the controller instance, the host can call its methods and read its values and targets: `this.countdownOutlet.pause()`, `this.countdownOutlet.secondsValue`. A namespaced identifier drops its delimiter in property names: an outlet declared as `exams--countdown` is read as `this.examsCountdownOutlet`. ## Outlet callbacks Define `countdownOutletConnected(outlet, element)` and `countdownOutletDisconnected(outlet, element)` to react as outlets come and go: - they fire whenever a matching countdown controller connects or disconnects while the host is connected, for instance when a lazy Turbo Frame loads the timer after the page, or a Turbo Stream removes it; - outlets already on the page when the host connects are reported as the outlet observer starts, which happens before the host's `connect()` runs; - changing the selector attribute on the host re-evaluates which elements count. Use them to enable controls only once a timer exists, or to stop calling into one that is gone. ## Pitfalls - **Name mismatch.** The outlet name must be the outlet's identifier. Declaring `static outlets = ["timer"]` while the element says `data-controller="countdown"` finds nothing. - **Assuming presence.** The singular getters throw when nothing matches. Guard optional outlets with `hasCountdownOutlet`. - **Unregistered controller.** `hasCountdownOutlet` checks the element and its `data-controller` attribute, not whether a `countdown` class is registered. If it is not, the singular getter throws that the element is missing an outlet controller instance. - **Hidden coupling.** The host now depends on the countdown's method names. That is fine for a deliberate collaborator, and a reason to prefer events when a controller only needs to announce something. ## Debugging an outlet that never connects 1. Check the outlet name in `static outlets` against the outlet's `data-controller` identifier, character for character, including any `--` namespace. 2. Check the attribute name on the host: `data-<host identifier>-<outlet name>-outlet`, on the host controller's own element. 3. Run the selector with `document.querySelectorAll` in the console; it must match the intended element and nothing else. 4. Confirm the outlet controller is registered and connected, for example through `window.Stimulus` in a Rails app, or by enabling `application.debug`. 5. If the outlet arrives later, rely on `countdownOutletConnected` rather than reading the property in `connect()`. ## Outlets and the page lifecycle Outlet properties re-query the document each time you read them, so after a Turbo Drive visit or a frame swap the host reaches the current countdown instance, not a stale one. The callbacks give a hook for that moment, and the host never has to store the instance itself.

  • How is an outlet different from a target?
    A target is an element marked inside the controller's own scope. An outlet is another controller, found anywhere in the document by a selector on the host element, and the main property returns that controller's instance rather than an element, so you can call its methods.
  • The countdown arrives later in a lazy Turbo Frame. How does the navigator find out?
    Stimulus watches the document for elements matching the outlet selector with the right identifier. When the frame's countdown controller connects, the host's `countdownOutletConnected(outlet, element)` fires, so the navigator can enable its controls then.
  • Why might hasCountdownOutlet be true while this.countdownOutlet throws?
    The existential property only checks for an element matching the selector with `countdown` in `data-controller`. If no `countdown` controller is registered, there is no instance to return, so the singular getter throws that the outlet controller instance is missing.

  • Outlets only find controllers nested inside the host's element
  • this.countdownOutlet returns the outlet's DOM element
  • Any element matching the selector is an outlet, data-controller or not
  • The outlet name can differ from the outlet controller's identifier
  • this.countdownOutlet returns null when nothing matches