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?
answer
- same path, replace action
- two meta tags in the head
- idiomorph patches only what changed
- needs yield :head in the layout
- other navigations still swap the body
basics
~20 sThey 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 sTurbo 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<%# 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
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.
Define a page refresh (same path, replace action), name the two meta tags and defaults, and explain why the helper needs yield :head.
Explain idiomorph's id-based matching, choose which pages morph, and handle client-side state that a morph would overwrite.
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.