| name | turbo |
| description | Expert guidance for building modern Rails UIs with Turbo (Drive, Frames, Streams). Use when implementing partial page updates, real-time broadcasts, turbo frames, turbo streams, hotwire patterns, turbo_frame_tag, turbo_stream responses, lazy loading frames, morphing, page refreshes, or any "turbo" related Rails feature. Covers Turbo Drive navigation, Turbo Frames for scoped updates, Turbo Streams for real-time HTML delivery, and Turbo 8 morphing. |
| allowed-tools | Read, Grep, Glob, Write, Edit, Bash(bin/rails generate *), Bash(bin/rails server) |
Rails Turbo Expert
Build fast, modern Rails UIs with zero (or minimal) custom JavaScript using Turbo Drive, Frames, and Streams.
Philosophy
Core Principles:
- HTML over the wire — The server renders HTML. Turbo delivers it. No JSON APIs for UI.
- Progressive enhancement — Turbo Drive works automatically. Frames and Streams layer on top.
- Server is the source of truth — Business logic stays in Ruby. Turbo just moves HTML around.
- Minimal JavaScript — If you're writing JS to update the DOM, you're probably doing it wrong. Use Turbo Streams.
- Composable primitives — Drive, Frames, and Streams each solve one problem. Combine them.
The Mental Model:
Turbo Drive → Speeds up ALL navigation (automatic, zero config)
Turbo Frames → Scopes updates to a REGION of the page (explicit, per-element)
Turbo Streams → Delivers TARGETED mutations to ANY element (server-pushed or response)
Decision Tree:
Need faster page loads? → Turbo Drive (already on)
Need to update PART of a page on click? → Turbo Frame
Need to update MULTIPLE parts at once? → Turbo Stream
Need real-time updates from other users? → Turbo Stream + ActionCable broadcast
Need smooth page refresh without flicker? → Turbo Morph (Rails 8+)
When To Use This Skill
- Adding turbo_frame_tag to scope navigation/updates
- Returning turbo_stream responses from controller actions
- Setting up real-time broadcasts with ActionCable
- Implementing lazy-loaded content
- Building inline editing, tabbed interfaces, modals
- Configuring Turbo Drive behavior (disabling for specific links/forms)
- Using Turbo 8 morphing and page refreshes
Instructions
Step 1: Understand What's Already There
Turbo Drive is on by default in every Rails 7+ app. You don't install it. You don't configure it. Every link click and form submission already goes through Turbo Drive.
Check the app has turbo-rails:
grep "turbo-rails" Gemfile
rg "import.*turbo" app/javascript/
If missing (unlikely in Rails 7+):
bundle add turbo-rails
bin/rails turbo:install
Step 2: Turbo Drive — Know When to Opt Out
Turbo Drive intercepts every <a> click and <form> submit, fetches via AJAX, and swaps the <body>. This is automatic. You only intervene to disable it.
<%# Disable for a specific link or form %>
<%= link_to "External Site", "https://example.com", data: { turbo: false } %>
<%= form_with model: @upload, data: { turbo: false } do |f| %>
<%# Disable for a whole section %>
<div data-turbo="false">...</div>
Common opt-out scenarios: file uploads (without Active Storage direct upload), external links, OAuth/SSO redirects, file downloads, payment forms (Stripe).
Non-GET link methods — prefer button_to over link_to with turbo_method:
<%# Acceptable %>
<%= link_to "Delete", post_path(@post), data: { turbo_method: :delete, turbo_confirm: "Sure?" } %>
<%# Better — more accessible and semantic %>
<%= button_to "Delete", post_path(@post), method: :delete,
form: { data: { turbo_confirm: "Are you sure?" } } %>
Step 3: Turbo Frames — Scoped Page Updates
Turbo Frames are the workhorse. They scope navigation to a region of the page. When a link or form inside a frame is clicked, only that frame updates.
⚠️ THE #1 AGENT MISTAKE: Forgetting to wrap BOTH sides in matching turbo_frame_tag.
The frame on the current page AND the response page must have a <turbo-frame> with the same ID. If they don't match, you get a Content Missing error.
Basic Frame Pattern:
<%# index.html.erb — the page with the frame %>
<%= turbo_frame_tag "post_#{@post.id}" do %>
<h2><%= @post.title %></h2>
<%= link_to "Edit", edit_post_path(@post) %>
<% end %>
<%# edit.html.erb — the response MUST have matching frame %>
<%= turbo_frame_tag "post_#{@post.id}" do %>
<%= render "form", post: @post %>
<% end %>
Use dom_id for consistent IDs:
<%= turbo_frame_tag dom_id(@post) do %>
<%# dom_id(@post) produces "post_123" %>
<% end %>
Lazy-loaded frames (load content after page render):
<%= turbo_frame_tag "comments", src: post_comments_path(@post), loading: :lazy do %>
<p>Loading comments...</p>
<% end %>
The src URL is fetched automatically. The loading: :lazy defers until the frame is visible (Intersection Observer). Without :lazy, it loads immediately after page load.
⚠️ AGENT GOTCHA: The lazy-loaded endpoint must return a page with a matching turbo_frame_tag. The controller doesn't need to know it's a frame — it renders normally, and Turbo extracts the matching frame.
Breaking out of a frame (target the whole page):
<%= turbo_frame_tag dom_id(@post) do %>
<%# This link stays in the frame %>
<%= link_to "Edit", edit_post_path(@post) %>
<%# This link breaks out and navigates the full page %>
<%= link_to "Show Full Page", post_path(@post), data: { turbo_frame: "_top" } %>
<% end %>
Target a DIFFERENT frame:
<%= turbo_frame_tag "sidebar" do %>
<%= link_to "Load Details", post_path(@post), data: { turbo_frame: "main_content" } %>
<% end %>
<%# This frame will be updated instead %>
<%= turbo_frame_tag "main_content" do %>
<p>Select a post from the sidebar</p>
<% end %>
Frame with custom target attribute (all links inside target another frame):
<%= turbo_frame_tag "nav", target: "main_content" do %>
<%# ALL links here update "main_content" frame instead %>
<%= link_to "Posts", posts_path %>
<%= link_to "Users", users_path %>
<% end %>
Step 4: Turbo Streams — Targeted DOM Mutations
Turbo Streams are surgical. They say "take this HTML and append/replace/remove it at this DOM target." They work in two contexts:
- HTTP responses — returned from form submissions (POST/PUT/PATCH/DELETE)
- WebSocket broadcasts — pushed to all connected users via ActionCable
The 7 stream actions:
| Action | What it does |
|---|
append | Add HTML to END of target's children |
prepend | Add HTML to START of target's children |
replace | Replace the ENTIRE target element |
update | Replace the INNER HTML of target |
remove | Remove the target element |
before | Insert HTML BEFORE the target |
after | Insert HTML AFTER the target |
⚠️ CRITICAL DISTINCTION: replace vs update
replace — removes the target element itself and puts new HTML in its placeupdate — keeps the target element, replaces its children
<%# replace: <div id="post_1"> is GONE, replaced entirely %>
<%= turbo_stream.replace dom_id(@post), partial: "posts/post", locals: { post: @post } %>
<%# update: <div id="post_1"> stays, its contents are swapped %>
<%= turbo_stream.update dom_id(@post), partial: "posts/post", locals: { post: @post } %>
Responding with Turbo Streams from a controller:
def create
@post = Post.new(post_params)
respond_to do |format|
if @post.save
format.turbo_stream
format.html { redirect_to @post }
else
format.html { render :new, status: :unprocessable_entity }
end
end
end
<%# app/views/posts/create.turbo_stream.erb %>
<%= turbo_stream.prepend "posts", partial: "posts/post", locals: { post: @post } %>
<%= turbo_stream.update "post_count", html: "#{Post.count} posts" %>
<%= turbo_stream.update "new_post_form" do %>
<%= render "form", post: Post.new %>
<% end %>
⚠️ AGENT GOTCHA: Turbo Stream responses ONLY work for non-GET requests. GET requests use Turbo Drive or Frames. If you try to return a turbo_stream format from a GET, it won't work. Use a frame instead.
Inline stream rendering (skip the template):
def destroy
@post.destroy
respond_to do |format|
format.turbo_stream { render turbo_stream: turbo_stream.remove(dom_id(@post)) }
format.html { redirect_to posts_path }
end
end
Multiple stream actions inline:
format.turbo_stream do
render turbo_stream: [
turbo_stream.remove(dom_id(@post)),
turbo_stream.update("post_count", html: "#{Post.count} posts")
]
end
Step 5: Turbo Stream Broadcasts (Real-Time)
Broadcasts push Turbo Stream actions to all users subscribed to a channel via ActionCable. This is how you get "real-time" without writing any JavaScript.
Setup the subscription in the view:
<%# This creates an ActionCable subscription %>
<%= turbo_stream_from "posts" %>
<%# Scoped to a specific record %>
<%= turbo_stream_from @project %>
<%# Multiple stream names %>
<%= turbo_stream_from @project, "messages" %>
Broadcast from the model:
class Post < ApplicationRecord
after_create_commit { broadcast_append_to "posts" }
after_update_commit { broadcast_replace_to "posts" }
after_destroy_commit { broadcast_remove_to "posts" }
broadcasts_to ->(post) { "posts" }
broadcasts_to :project
end
Broadcast with a custom partial:
after_create_commit do
broadcast_append_to "posts",
target: "posts_list",
partial: "posts/post_card",
locals: { post: self }
end
Broadcast from anywhere (controller, job, service):
Turbo::StreamsChannel.broadcast_append_to("posts", target: "posts_list",
partial: "posts/post", locals: { post: @post })
Turbo::StreamsChannel.broadcast_remove_to("posts", target: dom_id(@post))
⚠️ AGENT GOTCHA: Broadcasts render partials WITHOUT a request context. This means no current_user, no request, no session. Design your partials to work without these, or pass needed data as locals.
Step 6: Turbo 8 Morphing (Rails 8+)
Morphing is a page-refresh strategy that updates the DOM by diffing instead of replacing. It preserves form state, scroll position, and CSS transitions.
Enable morphing for a page:
<%# In the <head> of your layout or page %>
<%= turbo_refreshes_with method: :morph, scroll: :preserve %>
What this does:
method: :morph — Diffs the new HTML against current DOM, applies minimal changesscroll: :preserve — Keeps scroll position after refresh
Triggering a morph refresh from the server:
after_update_commit do
broadcast_refresh_to "posts"
end
broadcasts_refreshes
When to use morph vs streams:
- Morph — When you want to re-render the whole page but keep state (forms, scroll)
- Streams — When you want surgical, targeted updates to specific elements
Mark elements to preserve across morphs:
<div id="player" data-turbo-permanent>
<%# This element survives morph refreshes intact %>
</div>
Step 7: Forms in Turbo
Forms are where Turbo trips up agents the most. Key rules:
Rule 1: Failed validations MUST return 422 Unprocessable Entity.
def create
@post = Post.new(post_params)
if @post.save
redirect_to @post
else
render :new, status: :unprocessable_entity
end
end
Without :unprocessable_entity, Turbo won't render the error response. It'll follow the redirect status instead.
Rule 2: Forms inside frames stay in frames.
<%= turbo_frame_tag "new_post" do %>
<%= form_with model: Post.new do |f| %>
<%= f.text_field :title %>
<%= f.submit "Create" %>
<% end %>
<% end %>
The form submits via Turbo. The response must contain a matching turbo_frame_tag "new_post". OR the controller responds with turbo_stream format to skip the frame requirement.
Rule 3: Redirect after successful form submission.
if @post.save
redirect_to @post, notice: "Created!"
end
Rule 4: form_with uses Turbo by default in Rails 7+. No local: false needed. To disable:
<%= form_with model: @post, data: { turbo: false } do |f| %>
Step 8: Common Patterns
See the references/ directory for detailed implementations:
references/frames.md — Inline editing, tab navigation, lazy loading, modals, infinite scrollreferences/streams.md — Flash messages, live search, nested forms, counters, toasts, template conventionsreferences/broadcasting.md — Scoped broadcasts, user-specific streams, background job patternsreferences/morphing.md — Turbo 8 morph refresh setup, when to use morph vs streamsreferences/testing.md — Integration tests, system tests, broadcast assertionsreferences/edge-cases.md — Stimulus integration, gotchas (file uploads, DELETE redirects, CSP, caching)
Quick Reference
Helper Methods
<%# Frames %>
<%= turbo_frame_tag "id" %>
<%= turbo_frame_tag dom_id(@record) %>
<%= turbo_frame_tag "id", src: path, loading: :lazy %>
<%= turbo_frame_tag "id", target: "_top" %>
<%# Stream subscription %>
<%= turbo_stream_from "channel_name" %>
<%= turbo_stream_from @record %>
<%# Stream actions (in .turbo_stream.erb templates) %>
<%= turbo_stream.append "target_id", partial: "partial" %>
<%= turbo_stream.prepend "target_id", partial: "partial" %>
<%= turbo_stream.replace dom_id(@record), partial: "partial" %>
<%= turbo_stream.update "target_id", html: "content" %>
<%= turbo_stream.remove dom_id(@record) %>
<%= turbo_stream.before dom_id(@record), partial: "partial" %>
<%= turbo_stream.after dom_id(@record), partial: "partial" %>
<%# Morphing (Rails 8+) %>
<%= turbo_refreshes_with method: :morph, scroll: :preserve %>
Data Attributes
data-turbo="false" <%# Disable Turbo for this element %>
data-turbo-method="delete" <%# HTTP method for link %>
data-turbo-confirm="Sure?" <%# Confirmation dialog %>
data-turbo-frame="_top" <%# Break out of frame %>
data-turbo-frame="frame_id" <%# Target specific frame %>
data-turbo-permanent <%# Preserve across morphs %>
data-turbo-temporary <%# Remove on morph refresh %>
data-turbo-action="advance" <%# Push to browser history %>
data-turbo-action="replace" <%# Replace browser history entry %>
Model Broadcast Methods
after_create_commit { broadcast_append_to "stream" }
after_update_commit { broadcast_replace_to "stream" }
after_destroy_commit { broadcast_remove_to "stream" }
broadcasts_to ->(record) { "stream_name" }
broadcasts_to :parent_association
broadcasts_refreshes
after_update_commit { broadcast_refresh_to "stream" }
Turbo::StreamsChannel.broadcast_append_to("stream", target: "id", partial: "path")
Turbo::StreamsChannel.broadcast_remove_to("stream", target: "id")
Turbo::StreamsChannel.broadcast_refresh_to("stream")
Controller Response Pattern
respond_to do |format|
if @record.save
format.turbo_stream
format.html { redirect_to @record }
else
format.html { render :new, status: :unprocessable_entity }
end
end
Common Agent Mistakes
- Missing matching frame IDs — Both pages need
turbo_frame_tag with same ID
- Returning 200 on validation failure — Must be
status: :unprocessable_entity (422)
- Turbo Stream on GET requests — Streams only work on POST/PUT/PATCH/DELETE
- Using
current_user in broadcast partials — No request context in broadcasts
- Forgetting
turbo_stream_from in the view — Broadcasts need a subscription
replace when you mean update — replace removes the target element entirely- Not using
dom_id — Manual IDs drift; dom_id(@post) is consistent
- Forgetting
after_*_commit — Use commit callbacks, not after_save for broadcasts
- No HTML fallback in
respond_to — Always include format.html for non-Turbo clients
- Lazy frame without placeholder content — Show loading state inside the frame tag
Anti-Patterns
- Building JSON APIs just for UI updates — Use Turbo Streams instead
- Writing JavaScript to swap DOM content — That's what Turbo does
- Nesting frames deeply — Keep it to 1-2 levels; complexity explodes
- Broadcasting every model change — Be selective; too many broadcasts = performance issues
- Giant turbo_stream.erb templates — Keep stream responses focused; 1-3 actions per response
- Using Turbo Frames for things that need Streams — If you need to update multiple unrelated areas, use Streams
- Skipping the HTML fallback — Your app should work without Turbo (progressive enhancement)
