Pagination

Installation

Poetry doesn't paginate your queries. kaminari, pagy (v43+), and will_paginate already do that well. One generator installs an adapter so the gem you use renders this library's Pagination component instead of its own markup. The adapter is generated into your app, host-owned code with no extra runtime dependency, yours to edit.

bundle add kaminari                      # or: pagy / will_paginate
bin/rails g poetry:pagination            # detects every loaded paginator
bin/rails g poetry:pagination kaminari   # or name one: kaminari | pagy | will_paginate

Per gem, that installs: a kaminari paginator template override (app/views/kaminari/_paginator.html.erb), a pagy nav helper (app/helpers/poetry_pagy_helper.rb), or a will_paginate link renderer (app/lib/poetry_link_renderer.rb).

Wire your controller

Nothing changes about how you paginate: each gem's own controller API stays. Only the view call differs per gem:

kaminari

# controller - kaminari's own API, unchanged
@products = Product.page(params[:page]).per(10)

# view - your existing call; poetry options ride along
<%= paginate @products, siblings: 2 %>

pagy

# controller - include Pagy::Method (ApplicationController), then
@pagy, @products = pagy(:offset, Product.all, limit: 10)

# view - the adapter's helper
<%= poetry_pagy_nav(@pagy) %>

will_paginate

Note that will_paginate is in maintenance mode and no longer receives new features (its last release was mid-2024). The adapter supports apps that already use it; for a new project, pick kaminari or pagy instead.

# controller - will_paginate's own API, unchanged
@products = Product.paginate(page: params[:page], per_page: 10)

# view - pass the adapter renderer; poetry options under poetry:
<%= will_paginate @products, renderer: PoetryLinkRenderer,
                  poetry: { edges: :icons } %>

The window, labels, and one page

Poetry owns the window: the visible pages come from siblings: and edges:, one look across all three gems. The gems' own window options (kaminari's window / outer_window, will_paginate's inner_window, pagy's slot count) deliberately do not apply. Labels stay Poetry's; pass previous_label: / next_label: to localize. At a single page every adapter renders nothing, matching the gems' own behavior.

The examples below are live: all three gems paginate one shared 120-item collection through the real generated adapters, and every nav reads the same ?page= param. Click any of them and all three page together.

Kaminari

<%= paginate @kaminari_items %>

Pagy

<%= poetry_pagy_nav(@pagy) %>

Will paginate

<%= will_paginate @will_paginate_items, renderer: PoetryLinkRenderer %>