<h1>Catalog</h1>
<%= turbo_frame_tag "products" do %>
<div class="product-grid" data-controller="frame">
<% @products.each do |product| %>
<%= render "products/card", product: product %>
<% end %>
</div>
<nav class="pagination">
<%= paginate @products, views_prefix: "escaping" %>
</nav>
<% end %>
module Pagination
class LinkRenderer < Kaminari::Helpers::Paginator
def page_tag(page)
Kaminari::Helpers::Page.new(@template, **@options.merge(page: page.number)).tap do |tag|
tag.instance_variable_set(:@options, tag_options)
end
end
private
def tag_options
@options.merge(remote: false, data: { turbo_frame: "_top" })
end
end
module LinkHelper
def link_to_next_page(scope, name, **options)
options[:data] = (options[:data] || {}).merge(turbo_frame: "_top")
super(scope, name, **options)
end
def link_to_previous_page(scope, name, **options)
options[:data] = (options[:data] || {}).merge(turbo_frame: "_top")
super(scope, name, **options)
end
end
end
ActionView::Base.include(Pagination::LinkHelper)
<%= paginator.render do -%>
<nav class="pagination-inner" role="navigation" aria-label="pager">
<%= first_page_tag unless current_page.first? %>
<%= prev_page_tag unless current_page.first? %>
<% each_page do |page| -%>
<% if page.left_outer? || page.right_outer? || page.inside_window? -%>
<%= link_to page.number,
url_for(params.to_unsafe_h.merge(page: page.number)),
remote: false,
data: { turbo_frame: "_top" },
class: ("active" if page.current?) %>
<% elsif !page.was_truncated? -%>
<%= gap_tag %>
<% end -%>
<% end -%>
<%= next_page_tag unless current_page.last? %>
<%= last_page_tag unless current_page.last? %>
</nav>
<% end -%>
import { Controller } from "@hotwired/stimulus";
export default class extends Controller {
connect() {
this.frame = this.element.closest("turbo-frame");
if (!this.frame) return;
this.onBeforeVisit = this.logEscape.bind(this);
document.addEventListener("turbo:before-frame-render", this.onBeforeVisit);
}
disconnect() {
document.removeEventListener("turbo:before-frame-render", this.onBeforeVisit);
}
logEscape(event) {
const link = event.target.activeElement;
if (link && link.dataset.turboFrame === "_top") {
console.debug(`Link escaping frame #${this.frame.id} to top-level navigation`);
}
}
}
This snippet demonstrates a subtle Turbo Frames gotcha: when a paginated list is rendered inside a turbo-frame, the pagination links generated by a gem like Kaminari inherit the frame's scope, so clicking "Next" replaces only the frame's contents rather than driving a full-page navigation and updating the browser URL. In many product listings that is exactly wrong — the page should feel like a normal paginated view, with the address bar reflecting ?page=2 so the state is shareable and bookmarkable.
The fix is to make the pagination links target _top, which tells Turbo to break out of the enclosing frame and perform a top-level visit. In products/index.html.erb, the product grid is wrapped in a turbo-frame tagged products so that other interactions (like filtering) can update just that region. The paginate call is passed params: { turbo_frame: "_top" } through a custom views partial, but the real work happens in PaginationLinkRenderer.
In PaginationLinkRenderer, a subclass of Kaminari::Helpers::Tag machinery, the page_url_for and link-building logic is overridden so every generated anchor carries data-turbo-frame="_top". This is cleaner than post-processing HTML or sprinkling attributes in templates, because it centralizes the behavior in one renderer that Kaminari uses for every page link, gap, and prev/next control.
The _paginator.html.erb partial shows the Kaminari override point: by defining a custom paginator partial, the renderer's link_to calls consistently emit the escape attribute. The Stimulus frame_controller.js handles the complementary case — when a link should stay inside the frame, data-turbo-frame is left alone, and the controller simply logs frame lifecycle events for debugging flaky navigations.
The trade-off is intentional: pagination becomes a real navigation (full history entry, scroll reset, URL change) rather than a cheap frame swap. That costs a slightly heavier request but buys correct back-button behavior and shareable URLs. A common pitfall is forgetting that _top also discards any unsaved frame state, so it should only be used where a fresh page load is acceptable. When a developer wants in-frame pagination instead, they omit _top and let the frame lazily reload its src.
Related snips
class CommentsController < ApplicationController
before_action :set_post
def create
@comment = @post.comments.build(comment_params)System test: asserting Turbo Stream responses
class Post < ApplicationRecord
belongs_to :author, class_name: 'User'
has_many :comments, dependent: :destroy
scope :published, -> { where.not(published_at: nil).where('published_at <= ?', Time.current) }
scope :draft, -> { where(published_at: nil) }ActiveRecord scopes for reusable query logic
module Api
module V1
class UsersController < BaseController
def show
user = User.includes(:profile).find(params[:id])ETags for conditional requests and caching
class PostsController < ApplicationController
def index
@posts = Post.includes(:author)
.order(created_at: :desc)
.page(params[:page])
.per(10)Turbo Frames: infinite scroll with lazy-loading frame
require "csv"
class PeopleCsvStream
include Enumerable
HEADERS = %w[id full_name email signed_up_at plan].freezeResilient CSV Export as a Streamed Response
<form data-controller="query-sync" data-action="change->query-sync#apply">
<select name="status" class="rounded border p-2">
<option value="">Any</option>
<option value="open">Open</option>
<option value="closed">Closed</option>
</select>Filter UI that syncs query params via Stimulus (no front-end router)
Share this code
Here's the card — post it anywhere.
