skip to content

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%

answer

  1. no morph action, a method attribute
  2. replace morphs the element itself
  3. update morphs its children
  4. refresh="morph" needs src
  5. frames reload during a page refresh

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.

solid answer

~40 s

Turbo 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 lines
ruby
class 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
end

go deeper

for a junior

Know that there is no morph stream action; you add method="morph" to replace or update to morph the target.

for a middle

Explain replace-morph versus update-morph, write turbo_stream.replace with method: :morph, and describe what refresh="morph" does for a src frame.

for a senior

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.

for a principal

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.