The Hotwire Club

Stimulus - Promise-Returning Outlet Methods

Wed, 22 Jul 2026 00:00:00 +0000

Premise

Stimulus controllers usually talk to each other via dispatched events. That works great for fire-and-forget notifications, but events have no return channel. Sometimes you want a request/response shape instead: ask a controller a question, wait for the answer, act on it.

Enter the deferred-promise pattern. The trick is simple: create a promise, stash its resolve function on the controller instance, and settle it later from a different event handler. Wrap that in a public method and you’ve turned a Stimulus controller into an await-able mini-API. Combine it with outlets (Challenge 51 used them for the toast controller) and any other controller can call it like a library function.

Starting Point

We have a list of items, each with a delete button. Deletion requires confirmation. A <dialog>-based confirm controller already exists with Yes / No buttons, and a list-item controller handles the delete action.

But right now the two talk via a custom event: the list-item controller dispatches a confirm:ask event, and then has to listen for a confirm:answer event to find out what the user clicked. The delete logic is split across two handlers (before-ask and after-answer), with state smeared in between to remember which item was pending deletion.

The HTML is fully wired: the list items live statically in index.html, so you can see every data attribute in one place, including the data-list-item-confirm-outlet attribute you’ll need later. The server handles the actual deletion via POST-redirect-GET.

Challenge

Rewrite the confirm controller to expose a single public method:

async ask(message) { /* returns Promise<boolean> */ }

Inside ask(), set the dialog text, show the dialog, and return a promise whose resolve is stored on this.
In the Yes / No action handlers, call this.resolve(true) / this.resolve(false) and close the dialog.
In the list-item controller, declare confirm as an outlet and collapse the two-handler dance into one linear method:

async delete(event) {
  event.preventDefault()
  if (await this.confirmOutlet.ask("Delete this item?")) {
    event.target.closest("form").requestSubmit()
  }
}

Here’s the target behavior: clicking a delete button opens the dialog, “Yes” removes the item, “No” leaves it alone, and the list-item controller reads top to bottom like synchronous code.

Reminder: the Node server simulates a Rails backend. If you make changes to index.js, restart with npm start.

Teaser

What should happen when the user dismisses the dialog with Escape, or by clicking the backdrop? Right now, nothing resolves the promise, so the caller awaits forever. Wire those escape hatches up to resolve(false) so callers never hang. Hint: the <dialog> element fires a close event that covers Escape for free.

Caveat

If ask() is called while a previous call is still pending, you’ll overwrite this.resolve and strand the first caller’s promise, which then never settles. Depending on your UX you can queue calls, reject the previous promise, or simply guard against concurrent asks by refusing (or ignoring) a second call while the dialog is open. Whatever you pick, make it deliberate: a promise that silently never resolves is one of the nastiest bugs to track down.

Stimulus - Optimistic Toast Notifications with Auto-Save

Tue, 26 May 2026 00:00:00 +0000

Premise

Here’s a pattern you’ll find in any app with inline-editable fields: change a value, auto-save it, show a little toast that confirms the save. It feels polished when it works. The problem is where that toast comes from.

The standard Hotwire approach is to let the server send the toast back as a Turbo Stream, something like turbo_stream.append "toast". That works, but the feedback is tied to the round trip latency. If the server takes 800ms to respond (database write, background job, whatever), the user stares at a silent form for 800ms wondering if anything happened. On a slow connection it’s even worse.

In Challenge 21 we explored optimistic UI at the DOM level, swapping a favorite button’s state instantly via an inline <turbo-stream> template and reconciling later with a Turbo 8 morph. This time the goal is different: we’re not morphing HTML, we’re firing a side-channel notification (a toast) the instant the request leaves the browser, before we have a response. If the server comes back with an error, a second toast follows up with the bad news. Instant feedback in the happy path, honest feedback in the sad path. No radio silence.

There are two twists here. First, instead of one monolithic controller we’ll build two small ones, an auto-save controller and a toast controller, and link them through a Stimulus outlet. The auto-save controller can call this.toastOutlet.show(...) without knowing anything about the toast’s internals. Second, the toast controller wraps Notyf, a tiny (~3 KB) notification library. Wrapping a third-party lib in a Stimulus controller is a pattern you’ll reach for often: the controller owns the lifecycle, the outlet exposes a clean API, and the rest of your app never imports the library directly.

Starting Point

We have a simple settings form with a few fields. The server introduces an artificial delay (800-1500ms) to simulate a real-world round trip, and returns a 422 error roughly 20% of the time so you can test the failure path.

The HTML is fully wired: each input has a data-action="change->auto-save#save" attribute, the form declares a data-auto-save-toast-outlet pointing at the toast container, and a <div id="toast-container" data-controller="toast"> sits at the bottom of the page. Notyf is already in the import map and its CSS is loaded via a CDN link tag.

Both controllers are registered but their methods are empty. The outlet declaration and data-action bindings are in place; you just need to fill in the logic.

Challenge

Fill in the two empty controller methods:

toast_controller#show(message, variant) - Notyf is already instantiated in connect(). Implement show(message, variant) so it calls this.notyf.success(message) or this.notyf.error(message) depending on the variant. Hint: Notyf uses error where our API says danger, so you’ll need to map the name.
auto_save_controller#save() - Build a FormData from the form, call this.toastOutlet.show("Saved!", "success") before the fetch, then send the request. If the response comes back with a non-ok status, fire a second toast: this.toastOutlet.show("Save failed", "danger"). The outlet wiring (static outlets = ["toast"] and the HTML attribute) is already in place.

The order matters: the optimistic toast fires the instant the request dispatches, not when the response arrives.

Here’s the target behavior: the moment you change a field, a green “Saved!” toast slides in immediately. If the server returns an error (the demo server fails randomly ~20% of the time), a red “Save failed” toast follows a beat later.

Reminder: the Node server simulates a Rails backend. If you make changes to index.js, restart with npm start.

Teaser

Two directions you could take this further. First, make the messages configurable per form via Stimulus values: data-auto-save-success-message-value="Profile updated" overrides the default “Saved!” text, so the same controller serves every auto-saving form without changes. Second, try replacing Notyf with a hand-rolled toast built from a <div> and CSS keyframes. The controller’s show() signature stays the same; only the internals change. That’s the benefit of wrapping the library in a controller: swapping implementations is invisible to every outlet consumer.

Caveat

Watch the debounce timing. If the user tabs through three fields in quick succession, you don’t want three overlapping requests and three “Saved!” toasts stacking up. A debounce of 300-500ms collapses rapid edits into a single request. But the toast should fire on the leading edge, when the request actually dispatches, not on the trailing edge of the debounce timer. Otherwise you lose the instant feeling that makes optimistic UI worth doing in the first place.

Turbo Drive - Shared Element View Transitions

Tue, 12 May 2026 00:00:00 +0000

Premise

This is the third installment in our View Transitions series. In Challenge 35 we built swiper-like page transitions with Turbo Drive, and in Challenge 38 we animated list appends with Turbo Streams. What we haven’t covered yet is the shared element transition, the one you know from native apps where a thumbnail in a grid smoothly morphs into the hero image on the detail page.

The View Transitions API makes this surprisingly straightforward. When two elements on different pages share the same view-transition-name, the browser automatically interpolates between their position, size, and appearance during a navigation. You don’t need a JavaScript animation library or manual coordinate math - you assign a name, and the browser handles the rest.

There’s one important constraint to keep in mind, though: that name must be unique per page. If two elements share the same view-transition-name at the same time, the entire transition aborts silently. In a gallery grid with dozens of thumbnails, that’s something you’ll need to think about.

Starting Point

We have a simple photo gallery. The index page shows a grid of cards, each with a thumbnail image and a title. Clicking a card navigates to a detail page that shows the same image enlarged as a hero, plus a body of text.

View Transitions are already enabled via the meta tag:

https://stackblitz.com/edit/turbo-drive-shared-element-transitions?file=index.html%3AL6

Right now, navigating between the index and a detail page triggers the default cross-fade, because no view-transition-name is set on any element yet. The stylesheet already contains some basic transition configuration, but it’s waiting for the names to be wired up.

Challenge

Make the clicked card’s image smoothly morph into the hero image on the detail page, and back again when the user navigates with the browser back button.

Two things need to happen:

Assign a unique view-transition-name to each card image on the index page. Each image needs its own name, because names must be unique per page. If two images share the same name, the transition breaks silently. Hint: inline styles are the cleanest way to bind a dynamic name to a DOM node.
Give the detail page’s hero image the same name as the card it came from. When the browser sees the same name disappearing on the old page and appearing on the new one, it creates the morph animation automatically.

Here’s what the result looks like - the thumbnail lifts out of the grid, scales up, and settles into the hero position on the detail page. Navigating back reverses the animation.

Reminder: the Node server simulates a Rails backend. If you make changes to index.js, restart with npm start.

Teaser

What happens when the user navigates backward? The morph plays in reverse by default, which already looks good. But you can go further: Turbo sets a data-turbo-visit-direction attribute on the <html> element during rendering. Try using it to apply a different easing curve or duration for the reverse transition, so that returning to the grid feels distinct from opening a detail page.

Caveat

The uniqueness constraint on view-transition-name is strict. If the same name appears on more than one element at any point during the transition, the browser aborts the entire animation and falls back to a hard cut. This is easy to trip over in a gallery - if your index page renders 20 thumbnails and you give all of them view-transition-name: hero, nothing will animate. Each card image needs its own scoped name.

In a Rails context, this maps naturally to the model ID: style="view-transition-name: photo-<%= photo.id %>". On the detail page only one hero image exists, so there’s no collision risk - just make sure the name matches the one from the index.

One more thing to watch for is Turbo’s page cache. If a cached version of the index page has view-transition-name set on elements that are also present in the incoming page, you might get duplicate names during the snapshot restoration. Test with caching enabled to make sure your transitions survive the round trip.

Turbo Frames - Error Boundaries

Tue, 28 Apr 2026 00:00:00 +0000

Premise

You’ve seen it: a Turbo Frame request hits a 500, and instead of anything useful, the user gets “Content Missing.” Or worse - a network blip leaves a lazy-loaded frame silently empty. No feedback, no way to recover.

React solved this years ago with Error Boundaries - a wrapper component that catches failures in its children and renders fallback UI. We can do the same thing in Hotwire with a Stimulus controller that listens for turbo:frame-missing and turbo:fetch-request-error, shows a clean error state, and offers a retry button.

Building on the frame lifecycle work from Challenge 44 (loading spinners) and Challenge 46 (form loading states) - this challenge handles the failure path.

Starting Point

We have a dashboard with three lazy-loaded Turbo Frames: Recent Activity, Notifications, and Billing. Each frame has a src attribute and loads independently on page load.

The server is a small Express app standing in for a Rails backend. It has three routes - but not all of them are healthy:

/frames/activity returns valid frame content.
/frames/notifications returns a 500 error (after a short delay) - a generic error page with no matching <turbo-frame>, which triggers turbo:frame-missing.
/frames/billing drops the connection, simulating a network failure that triggers turbo:fetch-request-error. Note: this one takes a while to show — the browser needs to time out the request before the error fires.

Right now, the notifications frame shows “Content Missing” and the billing frame stays stuck on its loading state. The error_boundary_controller.js has connect(), showError(), and retry() pre-filled. Your job is the two event handlers.

The error-boundary controller lives on a wrapper <div> around each frame, with the <turbo-frame> as a frame target and a <template> as an errorTemplate target. The action descriptors for turbo:frame-missing and turbo:fetch-request-error are wired on the frame element, bubbling up to the controller.

Challenge

One file needs work - error_boundary_controller.js:

The controller skeleton already handles connect(), showError(message), and retry() for you. The showError method clones the error template, fills in the [data-role="message"] element with the message you pass, and swaps it into the frame. Your job is the two event handlers — each one deals with a different type of failure:

Handle turbo:frame-missing. In handleFrameMissing, call event.preventDefault() to suppress the “Content Missing” message. Then read event.detail.response — it’s a standard Response object with the server’s error response. Extract the status code and pass a user-friendly message to showError(), e.g. "Something went wrong. Please try again later."
Handle turbo:fetch-request-error. In handleFetchError, call event.preventDefault() and pass a network-specific message to showError(). This time there’s no event.detail.response — the request never got a response. Instead, event.detail.error has the Error object describing the failure.

Here’s the end result - activity loads normally, notifications shows an error state instead of “Content Missing”, billing eventually shows a network error, and clicking Retry re-fetches:

Reminder: the Node server simulates a Rails backend. If you make changes to index.js, restart with npm start.

Teaser

What if you added exponential backoff - automatically retrying 3 times with increasing delays before showing the error UI? And could you announce failures to screen readers using an aria-live region on the error template?

Caveat

The two events cover different failure modes. turbo:frame-missing fires when the HTTP request succeeds (you get a response) but the HTML doesn’t contain a <turbo-frame> with a matching id - the typical case for 4xx/5xx error pages. turbo:fetch-request-error fires when the request itself fails at the network level - no response at all. You need both for a robust error boundary.

Also worth knowing: turbo:frame-missing provides event.detail.visit - a function that replaces the entire page with the error response. That’s Turbo’s built-in escape hatch, useful for auth redirects (e.g., 401 → login page). The error boundary pattern is better for partial failures where the rest of the page should keep working.

Turbo Streams - Custom Stream Actions - pushState

Tue, 14 Apr 2026 00:00:00 +0000

Premise

In Challenge 19 — building on Challenge 8 (inline stream tags) and Challenge 9 (custom actions) — we stored ephemeral state in localStorage. That worked, but the browser’s Back and Forward buttons don’t know about it. Hit Back after switching versions three times? You leave the page entirely.

history.pushState() fixes this — but the part most people overlook is the first argument: the state object. It stashes data directly in the history entry. When the user hits Back, popstate hands that object back in event.state. No URL parsing, no guessing — your Stimulus controller reads the state and knows exactly what to restore. The URL is for the user and for refresh; the state object is for your JavaScript. One human-facing, the other machine-facing.

Today we’re building a custom push_state stream action (the server pushes URL and state) and a Stimulus controller that reads it back on popstate. TurboPower ships this out of the box — here we’re building it from scratch.

Starting Point

We have a documentation page with a version selector — a <select> dropdown that lets you switch between v1.0, v2.0, and v3.0 of an API. The selector lives inside a Stimulus controller (version-selector), and the whole thing is wrapped in a form with data-turbo-stream set to true — which tells Turbo to send an Accept: text/vnd.turbo-stream.html header, so the server knows to respond with Turbo Stream actions instead of a full HTML page.

The server is a small Express app standing in for a Rails backend. The GET /versions/:version route does what a Rails controller with respond_to { |f| f.turbo_stream } would do: it checks for switch or restore params, sets Content-Type: text/vnd.turbo-stream.html, and returns a string of <turbo-stream> tags. If you make changes to index.js, restart with npm start.

The server is ready to respond with Turbo Streams that replace the content area and the selector itself — but nothing works yet. That’s your job.

The server already handles a ?version= query parameter on full page load — that part is done. What’s missing is the pushState/popstate wiring.

Challenge

Two files need work — app.js for the custom stream action, and the version_selector_controller.js for the Stimulus side:

Register a push_state custom stream action in app.js. The server already includes a <turbo-stream action="push_state"> tag in its response, with url and state attributes. Your action should read both and call history.pushState(state, "", url). The state attribute is JSON — it carries the restore URL that the Stimulus controller will need later on popstate. The url attribute is what the user sees in the address bar.
Implement navigate in the Stimulus controller. When the user picks a version from the dropdown, update the form’s action to the selected value and submit it. The form already has data-turbo-stream, so this triggers a Turbo Stream response. Disable the select while the request is in flight to prevent double-clicks.
Implement restore in the Stimulus controller. This method is wired to popstate@window in the controller’s action descriptor. When the user hits Back or Forward, the browser hands you the state object you stashed earlier — it’s sitting right there in event.state.restoreUrl. Use get() from @rails/request.js with responseKind: "turbo-stream" to fetch that URL. Notice: the restore URL already has restore=1 baked in, which tells the server to skip the push_state stream tag — otherwise you’d push a new history entry on every Back press, creating an infinite loop.

Here’s the end result — note the URL changing with each version switch, and Back/Forward restoring the correct version:

Teaser

Now that you’ve built push_state from scratch, try dropping in TurboPower and replacing your hand-rolled action with theirs. What would it take to combine this pattern with Turbo’s morphing and page refreshes?

Caveat

A common stumbling point: popstate only fires on actual Back/Forward navigation, never when you call pushState(). The forward direction (user picks a version) is handled by the stream action; the backward direction (user hits Back) is handled by the Stimulus controller’s restore method. Two different mechanisms, one unified UX.

Turbo Frames - Chained Selects

Tue, 24 Mar 2026 00:00:00 +0000

Premise

Pick a country, then pick a city — you’ve seen this pattern a thousand times. The second dropdown depends on what you chose in the first. In jQuery-land this meant fetching JSON and manually rebuilding <option> elements. In React, you’d manage loading states, store the fetched options in component state, and re-render. With Turbo Frames, the server just re-renders the HTML you already have.

The trick: wrap the dependent <select> in a <turbo-frame>, and when the first one changes, reload that frame with the selected value as a query parameter. The server filters the options and returns the updated frame. No JSON APIs, no manual DOM manipulation.

The Stimulus controller that ties it together is surprisingly small.

Starting Point

We have a simple form with a Country select. The city select doesn’t exist yet — it should only appear after a country has been chosen.

The server has a small dataset of countries and their cities, and accepts a country_id query parameter to return the matching city list. But nothing in the frontend triggers that yet.

Challenge

There’s an empty <turbo-frame id="city_select"> in the page. Your job is to wire up a Stimulus controller that loads the city select into that frame when a country is chosen:

When the country select changes, build a URL with the selected country_id as a query parameter and set it as the city frame’s src. The server already knows how to return the right cities — it just needs the parameter.
When the country select is reset to the placeholder, the city frame should go back to being empty.

Here’s a preview of the result:

Teaser

What if you had a third level — say, Country → City → Neighborhood? Can you extend the pattern so picking a city loads a neighborhood select into yet another frame?

Turbo Frames - Form Submission Loading States

Tue, 10 Mar 2026 00:00:00 +0000

Premise

In the Loading Spinner challenge, we added busy indicators for Turbo Frame navigations — links that swap frame content asynchronously.

But what about forms? When a user submits a form inside a Turbo Frame, Turbo handles the request and swaps the response, but gives zero visual feedback while it’s in flight. The button stays clickable, nothing changes on screen, and the user is left wondering if their click registered — especially on slow connections.

Back in the Rails-UJS days, we had data-disable-with to handle this. Turbo 8 has its own answer, but it’s not automatic.

Starting Point

We have a simple guest book inside a <turbo-frame>. The server stores entries in memory and redirects back to the frame after a 1.5 second delay — simulating a slow save.

The form lives inside the frame, so Turbo intercepts the submission and swaps the response automatically.

Try it: submit an entry and notice the dead silence while the request is in flight. No spinner, no disabled button, no feedback at all.

Challenge

Make the form feel responsive during submission:

The submit button should change its text and become disabled while the request is in flight. Look up Turbo 8’s successor to data-disable-with in the Turbo Handbook. You’ll need to edit the button markup in renderFrame() inside index.js — remember to restart the server with npm start after making changes there.
The frame itself should show some visual indication that it’s busy. Remember: Turbo sets [busy] and [aria-busy] on frames during requests — how can you use that in CSS?

Here’s a preview of the end result:

Teaser

Can you combine this with the <template>-based spinner approach from the Loading Spinner challenge?

Turbo Frames - Using External Forms

Tue, 03 Feb 2026 00:00:00 +0000

Premise

Turbo Frames are a great way to compartmentalize your user interface, but sometimes they require workarounds when it comes to state management.

One example of such a requirement is when you have to handle a form on your page that refers to <input>’s in separate <turbo-frame>s.

Starting Point

We’re building upon the Faceted Search with Stimulus and Turbo Frames challenge here, but add a new requirement: Search results should also be sortable by publication year, author name (first name in this case) and book title.

Remember that this uses a single Stimulus controller to wrap a form and swap a Turbo Frame’s contents to filter the results.

Challenge

The goal is not to alter the Stimulus controller at all. We want to just append a new query parameter, sort.

This query parameter could for example be set to

name_asc
name_desc
title_asc
title_desc.

Now I’m going to require a bit fantasy from you, because we are going to look at the NodeJS part of our example here on Stackblitz. I’ve implemented the actual sorting in pure JavaScript here - you have to imagine that in fact we are looking at a Rails controller:

https://stackblitz.com/edit/turbo-frames-external-forms?file=index.js%3AL101

This is sorted list is wrapped in a Turbo Frame inside the server response. What’s missing is the configuration of a select box that should

hold an option for every sort parameter and direction
somehow refer to the <form> that’s outside the Turbo Frame, here (?! 🤯)

To try this out you’ll have to kill the node server in Stackblitz and restart it with npm start.

Here’s a preview of the result:

Granted, this is a bit of a contrived example (we could just hoist the sort dropdown to the form), but there will be other, more complex views where you’ll be glad you know about this approach. For example, you might want to reuse the turbo frame with sorting in other contexts.

Hint: Look up a form input’s possible attributes on MDN!

Turbo Frames - Loading Spinner

Tue, 20 Jan 2026 00:00:00 +0000

Premise

Asynchronously loading content via Turbo Frames sometimes comes with a user experience degradation because the frame doesn’t advertise its busy status, and/or becomes unresponsive.

Starting Point

We start with a quite simplistic page that has a bullet point navigation and a Turbo Frame for the contents:

<ul>
  <li><a href="/page1" data-turbo-frame="async-loader">Load Page 1</a></li>
  <li><a href="/page2" data-turbo-frame="async-loader">Load Page 2</a></li>
</ul>

<turbo-frame id="async-loader" src="/page1">
  >
</turbo-frame>

Observe that the links in the navigation point to the async-loader Turbo Frame, i.e. its src attribute is targeted.

The NodeJS backend is set up so that it returns page1.html and page2.html respectively:

https://stackblitz.com/edit/turbo-frames-loading-spinner?file=index.js%3AL12

These two pages contain just the Turbo frame to exchange:

<!-- page1.html -->
<turbo-frame id="async-loader"><span>Page 1 took 1 sec to load<span></turbo-frame>
<!-- page2.html -->
<turbo-frame id="async-loader">Page 2 took 2 sec to load</turbo-frame>

Challenge

To implement loading/busy feedback, use the <template> fragment supplied in the index page:

  <template data-frame-spinner-target="placeholder"
    >↻ Spinner, <em>can be any</em> <strong>HTML</strong></template
  >

https://stackblitz.com/edit/turbo-frames-loading-spinner?file=index.html%3AL46

The crucial point is to clone this fragment and insert it when the busy attribute appears, and remove it afterwards. For this we make use of a MutationObserver in a Stimulus controller. Thankfully useMutation from the Stimulus Use project makes this trivial. Insert the HTML swapping logic here:

Here’s a preview of the end result:

Teaser

There’s a way to make this work only with CSS if you don’t need any HTML in the “loading” display!

Stimulus - Web Share API

Tue, 25 Nov 2025 00:00:00 +0000

Premise

Among the more esoteric native browser APIs there’s one that is mostly overlooked (well, tbh most of them are) and thus lead to a whole host of third-party solutions when in fact the browser already includes this capability out of the box: The Web Share API, which allows a site to share text, files, and URLs in a simple, standardized manner.

Note: Of course, there’s a caveat - Firefox does NOT support this functionality: https://caniuse.com/web-share

Starting Point

We start with a grid of four images from https://picsum.photos/. In the caption of each image, next to the title there’s a link that shows a share button. This link already contains the binding to the share Stimulus controller, along with several values and an action defined for each:

an action that points to share
a title value that contains the image name (unoriginally just Picsum’s ID)
a text value for sharing a description (in our case alt text) of the photo
a url value containing the image URL, and
a file value pointing to a downloadable resource to share (for demonstration purposes, again just the image URL).

https://stackblitz.com/edit/stimulus-web-share-api?file=index.html%3AL60

Challenge

Your challenge is to use the Web Share API - most notably navigator.share() and navigator.canShare - to complete the sharing solution using the provided share data values:

Here’s a preview of the result on Mac OS:

Caveat

You will have to use feature detection using canShare for certain share data values!