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?
answer
- navigation scoped to the frame
- Turbo-Frame header names the frame
- only the matching frame is kept
- turbo_frame_tag(contact) gives contact_42
- 422 re-render lands in the frame
basics
~20 sA 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 sWrap 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<%# 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
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.
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.
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.
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.