skip to content

Turbo Frames

Turbo Frames scope navigation to one region: a link or form inside a <turbo-frame> swaps only the frame with the matching id, and lazy frames load from src. Interviewers ask when frames fit.

on this pageshow

explore

questions

5

In a Rails 8.1 address book using Turbo Frames, how does editing a contact row in place work, and why must the frame ids match?

level: juniorimportance: must knowfreq 65%

answer

  1. navigation scoped to the frame
  2. Turbo-Frame header names the frame
  3. only the matching frame is kept
  4. turbo_frame_tag(contact) gives contact_42
  5. 422 re-render lands in the frame

basics

~20 s

A link or form inside a <turbo-frame> navigates only that frame: Turbo fetches the URL, finds the <turbo-frame> with the same id in the response and swaps its contents in. Everything else in the response is discarded, so the ids must match.

solid answer

~40 s

Wrap each contact row in `turbo_frame_tag contact`, which renders `<turbo-frame id="contact_42">`. A click on the row's Edit link is captured by the frame: Turbo fetches `/contacts/42/edit` with a `Turbo-Frame: contact_42` header, looks in the response for `<turbo-frame id="contact_42">` and replaces only the frame's contents with that element's contents. The rest of the response, title and layout included, is thrown away, which is why the edit view must wrap its form in a frame with the same id. Submitting the form stays in the frame too: a failed save rendered with 422 shows the errors in place, and a successful update redirects to a page that also renders `contact_42`, so the row returns to display mode. The pages still work on their own as full pages, because Turbo only extracts the frame.

code

erb · 12 lines
erb
<%# app/views/contacts/_contact.html.erb %>
<%= turbo_frame_tag contact do %>
  <span><%= contact.name %></span>
  <span><%= contact.email %></span>
  <%= link_to "Edit", edit_contact_path(contact) %>
<% end %>

<%# app/views/contacts/edit.html.erb %>
<h1>Edit contact</h1>
<%= turbo_frame_tag @contact do %>
  <%= render "form", contact: @contact %>
<% end %>

go deeper

for a junior

Recall that links and forms inside a turbo-frame update only that frame, and that the response must contain a turbo-frame with the same id; turbo_frame_tag contact gives contact_42.

for a middle

Walk through the Turbo-Frame header, the extraction of the matching element, the 422 re-render inside the frame and why the same views keep working as full pages.

for a senior

Choose frames for regions that navigate on their own, keep ids unique and stable across views, and know where frames stop fitting and Turbo Streams take over.

for a principal

Use frames to keep server-rendered views as the single source of truth, so in-place interactions add no second rendering path to maintain.

## What a Turbo Frame is A **Turbo Frame** is a `<turbo-frame>` custom element with an `id`. It turns the region it wraps into an independent navigation context: links and forms inside it update the frame instead of the whole page. In a Rails app the element is usually written with turbo-rails' `turbo_frame_tag` helper, which builds the id from its arguments: a record becomes its DOM id (`turbo_frame_tag @contact` gives `contact_42`), a record plus a string becomes `notes_contact_42`, and plain strings are joined with underscores. ## Editing a contact row in place The address-book index renders one frame per contact. The flow of an in-place edit: 1. The user clicks **Edit** inside `<turbo-frame id="contact_42">`. 2. Turbo sends `GET /contacts/42/edit` with the request header `Turbo-Frame: contact_42` and marks the frame `busy` and `aria-busy="true"`. 3. `ContactsController#edit` renders `edit.html.erb`, whose form is wrapped in `turbo_frame_tag @contact`. 4. Turbo parses the response, finds `turbo-frame#contact_42`, and replaces the **contents** of the current frame with the contents of that element. The `<turbo-frame>` element itself stays; Turbo updates its `src` to the URL it loaded and sets `complete`. 5. The user submits. The form is inside the frame, so the submission is scoped to it as well. 6. On a failed save the controller renders `:edit` with `status: :unprocessable_content`; Turbo renders the matching frame from that response, so the errors appear in the row. 7. On success the controller redirects to `contact_path(@contact)`; `fetch` follows the redirect, and the show page's `contact_42` frame (the row partial) replaces the form. ## Why the ids must match Turbo does not take the whole response. It looks for **one element**: a `<turbo-frame>` whose id equals the id of the frame being navigated. Everything outside it, including the `<h1>`, the layout and other frames, is discarded. Consequences: - If the edit view forgets the frame, or uses another id, the frame has nothing to show. Turbo fires `turbo:frame-missing` and, by default, writes "Content missing" into the frame. - Ids must be unique on the page, or Turbo cannot tell which element a response belongs to. Per-record ids from `turbo_frame_tag record` solve that for lists. - The same view works as a standalone page: opening `/contacts/42/edit` directly renders the full layout with the form, and the frame is just a wrapper. ## What the server sees | Request | `Turbo-Frame` header | turbo-rails layout | |---|---|---| | full page visit to `/contacts/42/edit` | absent | the application layout | | frame navigation from `contact_42` | `contact_42` | the minimal `turbo_rails/frame` layout | turbo-rails exposes `turbo_frame_request?` and `turbo_frame_request_id` to controllers and views, and swaps the layout for frame requests as a rendering optimisation. The controller code itself does not need to change: the same `edit` and `update` actions serve both cases. ## Forms inside a frame Frame-scoped form submissions follow the same response handling as page forms in the common cases: a redirect is followed and its frame extracted, and a 4xx response is rendered into the frame. One difference is worth knowing: a frame does not insist on a redirect, so a non-GET submission answered with a 200 page is rendered into the frame rather than refused. Rails convention still redirects after a successful write, which keeps the URL and history honest if the same form is ever used as a full page. ## Events around a frame render Turbo dispatches events on the frame element itself, and they bubble to the document: - `turbo:before-frame-render`, cancelable; a listener can pause rendering and later call `event.detail.resume()`, or replace `event.detail.render` with its own function; - `turbo:frame-render` right after the new contents are in place; - `turbo:frame-load` once the navigation has finished. A common use is focusing the first input after the edit form arrives, so keyboard users land in the form rather than at the top of the page. ## When a frame fits Frames suit regions that navigate independently: inline edit forms, tabs, paginated side panels, modals loaded on demand. They are the wrong tool when one action must update several unrelated parts of the page; that is a job for Turbo Streams. Wrapping content in a frame changes how every link and form inside it behaves, so frames should be introduced deliberately, not as generic containers.

  • What does turbo_frame_tag(@contact, "notes") render as the id, and why use it?
    It renders `<turbo-frame id="notes_contact_42">`: the extra string becomes a prefix to the record's DOM id. Use it when one record needs several independent frames on a page, for example a contact's details and its notes, so their ids stay unique.
  • Why does the h1 in the edit view not appear when the form loads inside the frame?
    Turbo extracts only the `<turbo-frame>` with the matching id from the response and discards everything outside it. The h1 sits outside the frame, so it is used only when the edit page is opened as a full page.
  • Can the server render just the frame instead of the whole edit page?
    It can, but it does not need to. turbo-rails already renders frame requests with the minimal `turbo_rails/frame` layout, and keeping the full view means the URL still works as a standalone page and in a new tab.

A Turbo Frame is one window pane in a house: you can pull out that pane and slot in a new one without rebuilding the house, but the new pane has to be cut for the same frame, or it does not fit.

  • Turbo replaces the frame with the whole response body, layout included.
  • Any <turbo-frame> in the response is used, whatever its id.
  • The edit action must detect the frame request and render a different template.
  • A Turbo Frame needs a Turbo Stream response to update its contents.
  • Two contact rows can share one frame id as long as they are in different lists.
  • A form inside a frame is submitted as a full-page Turbo Drive visit.
open as a page

With Turbo Frames, what does data-turbo-action="advance" change for a paginated contacts frame, and what must the Rails action then guarantee?

level: middleimportance: should knowfreq 30%

basics

~20 s

data-turbo-action="advance" promotes a frame navigation to a page visit: the frame updates and the browser URL moves to the frame's new URL with a history entry. The Rails action must render that URL correctly as a full page.

open as a page

With Turbo Frames in Rails 8.1, how do src and loading="lazy" defer part of a page, and what does turbo_frame_request? change on the server?

level: middleimportance: should knowfreq 45%

basics

~20 s

A <turbo-frame> with src fetches that URL after the page renders, at once by default or when it scrolls into view with loading="lazy". turbo_frame_request? tells Rails the request came from a frame, and turbo-rails then renders a minimal layout.

open as a page

With Turbo Frames, how do target="_top" and data-turbo-frame decide whether a link or form updates its own frame, another frame or the whole page?

level: middleimportance: should knowfreq 50%

basics

~20 s

Inside a frame, links and forms update that frame by default. target on the <turbo-frame> sets a default for its descendants, data-turbo-frame on a single link or form overrides it, and "_top" in either sends navigation to the whole page.

open as a page

A Rails 8.1 address book's contact frame shows 'Content missing' whenever a session expires mid-edit. Why does this happen, and how do you fix it?

level: seniorimportance: should knowfreq 32%

basics

~20 s

The frame's request is redirected to the login page, which has no frame with the expected id, so Turbo fires turbo:frame-missing and writes Content missing. Mark the login page turbo-visit-control reload, or handle turbo:frame-missing with a full visit.

open as a page