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?
answer
- no morph action, a method attribute
- replace morphs the element itself
- update morphs its children
- refresh="morph" needs src
- frames reload during a page refresh
basics
~20 sTurbo 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.
solid answer
~40 sTurbo 8 has exactly eight stream actions, and `morph` is not one of them. Instead, `<turbo-stream action="replace" method="morph">` morphs the target element into the template's element, and `action="update" method="morph"` morphs only its children; in Rails that is `turbo_stream.replace @chore, method: :morph` or the same option on `update`. Morphing keeps unchanged nodes, focus and listeners inside the target, which a plain replace would destroy. For frames, `refresh="morph"` matters only together with `src`. During a morphing page refresh such a frame is not morphed from the new page's copy; Turbo calls its `reload()`, re-fetches the `src` and morphs the result in. Content loaded into the frame after the page loaded, such as further pages of chores, therefore survives the refresh. Calling `frame.reload()` directly morphs too.
code
ruby · 10 linesclass ChoresController < ApplicationController
def update
@chore = Current.household.chores.find(params[:id])
@chore.update!(params.expect(chore: [:title, :done]))
respond_to do |format|
format.turbo_stream { render turbo_stream: turbo_stream.replace(@chore, method: :morph) }
format.html { redirect_to chores_path, status: :see_other }
end
end
endgo deeper
Know that there is no morph stream action; you add method="morph" to replace or update to morph the target.
Explain replace-morph versus update-morph, write turbo_stream.replace with method: :morph, and describe what refresh="morph" does for a src frame.
Use morph on targeted streams where focus or state inside the target matters, and protect separately loaded regions in morphing pages with refresh="morph" frames.
Standardise on stable ids and a small set of morph patterns so targeted updates and page refreshes behave the same way across the app.
## Morph is a method, not an action The Turbo 8 source defines eight stream actions: `after`, `append`, `before`, `prepend`, `remove`, `replace`, `update` and `refresh`. The Turbo handbook's streams page counts a ninth, `morph`, but the source wins: there is no such action, and an unknown action raises an error. Morphing a stream target is done with an attribute on two existing actions: | Markup | Without `method` | With `method="morph"` | |---|---|---| | `action="replace"` | the target is replaced by the template's element | the target element is morphed into it | | `action="update"` | the target's children are replaced | the target's children are morphed | turbo-rails exposes it as an option on the builder: ```erb <%# app/views/chores/update.turbo_stream.erb %> <%= turbo_stream.replace @chore, method: :morph %> <%= turbo_stream.update "chore_summary", partial: "chores/summary", method: :morph %> ``` The generic `action` builder method takes `method:` as well; `append`, `prepend`, `before` and `after` do not. ## Why morph a single target A plain `replace` throws the old element away and inserts a new one. Everything attached to the old node goes with it: - focus inside it, so a keyboard user loses their place; - event listeners and Stimulus controllers, which disconnect and reconnect; - CSS transitions, which restart; - form inputs inside it, which lose what the user typed. With `method="morph"`, idiomorph changes only what differs. For a chore row whose title and checkbox state changed, the row element and its other children stay the same nodes. Elements marked `data-turbo-permanent` are skipped, as in page morphs, and the per-element morph events fire. ## Frames that refresh with morphing A page refresh with `turbo-refresh-method` set to `morph` morphs the whole body, frames included. That is a problem for a frame whose content was loaded *after* the page, for example a `src` frame showing chores loaded with "Load more": the new page's copy of the frame is empty or holds only its placeholder, so morphing from it would wipe the loaded content. `refresh="morph"` handles that case: 1. Turbo checks each frame during the page morph. A frame qualifies when it has both `src` and `refresh="morph"`, matches the new page's frame by id, and is not inside a permanent element. 2. Instead of morphing it from the new page, Turbo calls the frame's `reload()`, which re-fetches its current `src`. 3. The response is rendered into the frame by morphing its children, dispatching `turbo:before-frame-morph` first. The frame's `refresh` attribute is ignored on a frame without `src`; the source only reloads with morphing when both are present. Calling `reload()` yourself on such a frame also uses morphing rather than a plain replacement. ```erb <%= turbo_frame_tag "chore_history", src: history_chores_path, refresh: "morph" %> ``` ## Events during targeted and frame morphs Stream and frame morphs go through the same Turbo callbacks as page morphs, so the per-element events fire for them too: - `turbo:before-morph-element` and `turbo:before-morph-attribute`, cancelable, for each element or attribute about to change; - `turbo:morph-element` after each element changes; - `turbo:before-frame-morph` on a frame just before its children are morphed. `turbo:morph` is different: it is dispatched only after a whole-page morph, so a listener waiting for it never runs for a stream or frame morph. ## Ids are the contract Every technique here depends on ids. A stream's `target` must match an element id on the page, which is why the Rails builders accept a record and convert it with `dom_id`. idiomorph then pairs the old and new nodes inside the target by their ids and the ids of their descendants. Rendering the same partial, with the same `dom_id` on each row, for the page, the stream and the frame keeps all three in agreement. ## Choosing between them - Use **`method: :morph` on a stream** when a controller or broadcast already targets one element and you want to keep focus or state inside it. - Use **`refresh="morph"` on frames** when a page morphs on refresh but contains regions loaded separately. - Use **`data-turbo-permanent`** when a region should not change at all during refreshes. All three rely on stable ids, because both the stream target and idiomorph's matching depend on them.
- Why would a page morph wipe a frame of chores loaded with 'Load more', and how does refresh="morph" avoid it?The new page's copy of the frame holds only its initial content, so morphing from it removes what the frame loaded later. With `src` and `refresh="morph"`, Turbo skips that comparison, reloads the frame from its current `src` and morphs the response in, keeping the loaded state.
- What is the difference between method="morph" on replace and on update?On `replace`, the target element itself is morphed into the template's element, so its own attributes can change. On `update`, only the target's children are morphed and the target element's attributes stay as they are.
- A plain replace stream keeps focus and listeners inside the target element.
- refresh="morph" on a frame without src reloads it during page refreshes.
- method: :morph on turbo_stream.append morphs new rows into the list.
- A morphed replace disconnects and reconnects every Stimulus controller inside it.
- During a morphing page refresh, refresh="morph" frames are emptied and refilled from the new page.
Assumes Turbo 8 (8.0.23 source: eight stream actions, morph as method="morph" on replace/update) with turbo-rails 2.0.x on Rails 8.1.