The Hotwire Club

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!

Turbo Frames - Typeahead Validation

Mon, 20 Oct 2025 00:00:00 +0000

Premise

Sometimes your application requires validating user input in real time. In order to maximize user experience, for example, you might want to report whether a certain email address, time slot etc. has been taken.

We are going to explore how this can be achieved just with native Turbo Frames form submission handling and a few client-side event hooks.

Starting Point

Let’s explore the server side code first. I’ve again replicated a basic Rails controller in Node.js again. The /subdomain/edit route uses the form.html template to return, you guessed it, the form. It’s populated with the current value, whether that value is invalid, and a helper text:

https://stackblitz.com/edit/turbo-typeahead-validation?file=index.js%3AL21

Emulating an update action, we respond to a PATCH request on /subdomain with either 200 (OK) or 422 (Unprocessable Content) depending on whether the subdomain we entered is contained in a list of taken subdomains:

https://stackblitz.com/edit/turbo-typeahead-validation?file=index.js%3AL42

Continuing to the client, our index.html only contains a reference to an eager loaded Turbo Frame pointing to said /subdomain/edit route:

https://stackblitz.com/edit/turbo-typeahead-validation?file=index.html%3AL41

I’ve also included an event handler that listens for the input event of the text field and sets off a form submission:

https://stackblitz.com/edit/turbo-typeahead-validation?file=app.js%3AL10

Note: In reality you’d likely want to debounce this to save bandwidth and not overload your server.

Challenge

Currently the form is practically unusable because the text field loses focus and we have to manually click into it again. We could use autofocus but that leads to other issues down the road (trust me on this one).

Your task is to

somehow capture and store the activeElement (the one with focus, i.e. the text field),
and the current caret positition on turbo:submit-start
and restore both on turbo:frame-render.

Here’s a preview of the result:

Caveat

You will learn why morphing libraries such as Idiomorph or morphdom require IDs being set on HTML elements 😉.

Teaser

What would it take to make this solution portable, for example in a Stimulus controller?

Turbo Streams - List Animations Using the View Transitions API

Tue, 10 Jun 2025 00:00:00 +0000

Premise

Since I always try to trace out a (web) technology from multiple angles, I wanted to test whether there’d be a use case for View Transitions with Turbo Streams, too.

That use case arrived when I had to implement infinite loading using a “Load more” button for a client project. I had a list of items to which more were added using a <turbo-stream action="append"> action. What was asked for was a smooth animation for this event.

I could’ve used any CSS animation using a class and a timed JavaScript callback to remove that class again, but I wanted to see if View Transitions could do the job, and perhaps more elegantly.

Starting Point

We start with a simple list of tickets, with an ID of tickets. Beneath it there’s a “Load More” button wrapped in a <form>:

https://stackblitz.com/edit/turbo-streams-view-transitions?file=index.html%3AL42

The form’s action points to the / route which responds with a <turbo-stream> to mimic the typical behavior of a Ruby on Rails controller:

https://stackblitz.com/edit/turbo-streams-view-transitions?file=index.js%3AL12

In the stylesheet I’ve prepared a view transition named new-ticket which uses an animation to slide in the respective new element from the right:

https://stackblitz.com/edit/turbo-streams-view-transitions?file=styles.css

Challenge

Akin to Turbo Frames, Turbo Streams also fire a turbo:before-stream-render event that allows to customize the render method.

Your task is, similar to the preceding challenges, to overwrite the original render method. Note that you have to manually invoke a same document transition again!

Here’s a look at the result:

Caveat

Keep in mind that a view-transition-name must be unique across the elements of a page!