skip to content

Morphing Page Refreshes

Turbo 8 refreshes a page by morphing the DOM with idiomorph instead of replacing the body, keeping scroll and permanent elements. Interviewers ask when a morph beats targeted streams.

on this pageshow

explore

questions

5

In a Rails 8.1 app on Turbo 8, what do turbo_refreshes_with(method: :morph, scroll: :preserve) change when a chores form redirects back to the same page?

level: middleimportance: must knowfreq 45%

answer

  1. same path, replace action
  2. two meta tags in the head
  3. idiomorph patches only what changed
  4. needs yield :head in the layout
  5. other navigations still swap the body

basics

~20 s

They add turbo-refresh-method morph and turbo-refresh-scroll preserve meta tags. When a visit reloads the same path with the replace action, as a redirect back does, Turbo morphs the changed DOM with idiomorph and keeps the scroll position instead of swapping the body.

solid answer

~40 s

Turbo 8 treats a visit as a **page refresh** when it renders the same pathname with the `replace` action. A form that redirects back to the URL it was submitted from gets that action automatically, and so does a `refresh` stream. By default a refresh still replaces `<body>` and scrolls to the top. turbo-rails' `turbo_refreshes_with(method: :morph, scroll: :preserve)` writes `<meta name="turbo-refresh-method" content="morph">` and `<meta name="turbo-refresh-scroll" content="preserve">` through `provide :head`, so the layout must `yield :head`. With them, Turbo morphs the current body into the new one with idiomorph, touching only nodes that changed, and keeps the scroll offset. Ticking a chore halfway down a long list then updates that row in place. Navigation to a different page is unaffected: it swaps the body as before, meta tag or not. Invalid values raise `ArgumentError`.

code

erb · 11 lines
erb
<%# app/views/chores/index.html.erb %>
<% turbo_refreshes_with method: :morph, scroll: :preserve %>

<ul>
  <% @chores.each do |chore| %>
    <li id="<%= dom_id(chore) %>">
      <%= button_to (chore.done? ? "Undo" : "Done"), toggle_chore_path(chore), method: :patch %>
      <%= chore.title %>
    </li>
  <% end %>
</ul>

go deeper

for a junior

Know that turbo_refreshes_with method: :morph, scroll: :preserve makes a redirect back to the same page update in place and keep the scroll position.

for a middle

Define a page refresh (same path, replace action), name the two meta tags and defaults, and explain why the helper needs yield :head.

for a senior

Explain idiomorph's id-based matching, choose which pages morph, and handle client-side state that a morph would overwrite.

for a principal

Weigh morphing as a way to keep server-rendered pages feeling live without per-interaction client code, against the cost of full-page renders on every refresh.

## What counts as a page refresh Turbo Drive normally renders a visit by replacing `<body>` and scrolling to the top. Turbo 8 adds a special case, the **page refresh**: a render of the *same pathname* with the visit action `replace`. Three things produce one: - a form submission whose redirect lands on the URL the page is already showing, because Turbo picks `replace` for a same-location redirect; - a `<turbo-stream action="refresh">`, which re-fetches the current URL with a `replace` visit; - `Turbo.visit(window.location.href, { action: "replace" })` from code. Only page refreshes consult the refresh settings. Clicking through to another page still swaps the body, even when the page carries the morph meta tag. ## The two settings | Meta tag | Values | Default | Effect on a page refresh | |---|---|---|---| | `turbo-refresh-method` | `replace`, `morph` | `replace` | `morph` patches the existing DOM instead of swapping the body | | `turbo-refresh-scroll` | `reset`, `preserve` | `reset` | `preserve` keeps the vertical and horizontal scroll | turbo-rails wraps both in `turbo_refreshes_with(method: :replace, scroll: :reset)`. It calls `provide :head` with `turbo_refresh_method_tag` and `turbo_refresh_scroll_tag`, and raises `ArgumentError` for anything other than `replace`/`morph` and `reset`/`preserve`. Because it uses `provide :head`, the tags only appear if the layout renders `<%= yield :head %>` inside `<head>`; the Rails 8.1 generated layout does. The `_tag` helpers return the bare meta tags for layouts that build the head differently. ## How the morph works With `morph`, Turbo hands the current `<body>` and the response's `<body>` to **idiomorph**, the morphing library Turbo bundles (0.7.4 in Turbo 8.0.23). idiomorph walks both trees and edits the live DOM until it matches the new HTML: - elements that did not change are left as they are, with their listeners and focus; - changed attributes and text are updated in place; - new nodes are inserted and missing ones removed. To pair old and new nodes, idiomorph matches elements by `id`, and by the set of ids found among their descendants. Stable ids on list rows, such as the `dom_id` of each chore, therefore make a morph precise: it updates `chore_42` rather than rewriting the whole list. Turbo dispatches `turbo:morph` after a page morph, plus per-element events (`turbo:before-morph-element`, `turbo:before-morph-attribute`, `turbo:morph-element`) that let code veto or react to individual changes. Elements marked `data-turbo-permanent` are skipped. ## The chores list, end to end 1. The chores index calls `turbo_refreshes_with method: :morph, scroll: :preserve`. 2. A household member scrolls to the twentieth chore and ticks it; the form PATCHes `/chores/20`. 3. The controller updates the record and redirects to `chores_path` with `status: :see_other`. 4. The redirect lands on the URL the page is showing, so Turbo uses `replace`: a page refresh. 5. Turbo fetches `/chores`, morphs the body and keeps the scroll offset. Only chore 20's row and any counters change on screen. Without the settings, step 5 would swap the body and jump to the top of the list, which is exactly the jarring behaviour morphing was added to remove. ## Confirming a morph happened A quick check in development: add a `turbo:morph` listener that logs, tick a chore, and watch the console. If the log never appears, the visit was not a page refresh (a different path, or an `advance` action) or the meta tag is missing from the rendered `<head>`. Inspecting `<head>` for `turbo-refresh-method` answers the second question at once. ## Limits and gotchas - **Same pathname only.** Redirecting from `/chores/20/edit` back to `/chores` after the edit page was shown is a navigation to another page, so it is not morphed. Query strings matter for the redirect check: Turbo compares the full URL to pick `replace`. - **Client-side state can be overwritten.** idiomorph makes the DOM match the server's HTML, so a class or attribute added in the browser, such as an open menu, may be reset. `data-turbo-permanent` or a `turbo:before-morph-attribute` listener protects it. - **Full page cost.** A morph still renders and transfers the whole page; it saves DOM work and visual disruption, not server time. - **Stimulus controllers stay connected** on elements that survive a morph, which changes when `connect()` runs compared with a body swap. Setting the tags per page, rather than in the layout, keeps morphing on the screens that benefit (lists edited in place) and plain replacement elsewhere.

  • The page has the morph meta tag, yet clicking from the chores list to a chore's page still swaps the body. Is something broken?
    No. Turbo morphs only page refreshes: a render of the same pathname with the `replace` action. A link to a different page is an ordinary navigation, so Turbo replaces the body as usual whatever the meta tag says.
  • Why do stable ids on list rows matter for a morph?
    idiomorph pairs old and new elements by id and by the ids of their descendants. With `dom_id` on each row it can update the one row that changed; without ids it falls back to structural matching, which may rewrite more nodes than necessary.
  • What happens if turbo_refreshes_with is called but the layout has no yield :head?
    Nothing visible: the helper stores the meta tags with `provide :head`, and they are rendered only where the layout yields `:head`. Refreshes keep the defaults, replacing the body and resetting scroll.

A morphing refresh is a proofreader marking up yesterday's printout instead of reprinting the whole document: only the changed lines get corrected, and the reader keeps their place on the page.

  • With the morph meta tag, every Turbo Drive navigation morphs instead of swapping the body.
  • Morphing means the server renders only the changed parts of the page.
  • A refresh stream morphs the page even when the page has no morph meta tag.
  • turbo_refreshes_with works in any layout, whether or not it renders yield :head.
  • scroll: :preserve keeps the scroll position on every visit, not just refreshes.
  • Morphing replaces Turbo's diffing with React's virtual DOM under the hood.

Assumes Turbo 8 (8.0.23 source, bundling idiomorph 0.7.4) with turbo-rails 2.0.x on Rails 8.1, whose generated layout renders yield :head.

open as a page

During a Turbo 8 morphing refresh of a chores page, what does data-turbo-permanent protect, and what client-side state can a morph still reset?

level: juniorimportance: should knowfreq 28%

basics

~20 s

data-turbo-permanent tells Turbo to leave an element untouched, so morphing skips it entirely. Anything else is made to match the server's HTML, so classes or attributes changed in the browser, such as an open menu, can be reset.

open as a page

With turbo-rails, how does broadcasts_refreshes_to keep every open chores page current, and how are the resulting refreshes debounced and de-duplicated?

level: middleimportance: should knowfreq 30%

basics

~20 s

broadcasts_refreshes_to adds an after_commit callback that broadcasts a refresh stream to a named stream; pages subscribed with turbo_stream_from re-fetch and morph. A 0.5 s server debounce and a 150 ms client debounce coalesce bursts, and a request-id skips the sender's tab.

open as a page

For a household chores list edited by several people at once, when would you choose morphing refresh broadcasts over targeted Turbo Stream broadcasts, and why?

level: seniorimportance: should knowfreq 35%

basics

~20 s

Choose refresh broadcasts when the page is cheap to render and correctness matters more than bandwidth: every viewer re-renders the real page with their own session, so nothing drifts. Choose targeted streams for heavy pages, many viewers or high-frequency updates.

open as a page

In Turbo 8, how do method="morph" on replace and update stream actions and refresh="morph" on a turbo-frame bring morphing beyond page refreshes?

level: middleimportance: nice to knowfreq 20%

basics

~20 s

Turbo has no morph stream action: replace and update accept method="morph" to morph the target instead of swapping it. A frame with src and refresh="morph" is reloaded and morphed during a page refresh or reload() instead of being replaced.

open as a page