Pagy
The fastest and most efficient pagination Ruby gem — 40x faster and 100x more memory-efficient than kaminari or will_paginate. Pagy doesn't pollute models with pagination logic; works at the controller level. Key API: pagy(collection) returns [pagy, records] tuple; pagy_nav(pagy) renders pagination links in views. Supports: multiple pagination UI styles (bootstrap, bulma, tailwind, responsive), JSON API pagination metadata, cursor-based pagination (pagy-keyset for cursor), elasticsearch, searchkick, meilisearch integration. Pagy extras provide optional features without loading unused code. Rails standard includes pagy_metadata for JSON API pagination responses.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Pagination library — no network exposure. Page parameter should be validated as integer to prevent injection. Cursor values in keyset pagination should be signed/verified to prevent agent data access without proper authorization.
⚡ Reliability
Best When
You're building a Rails agent API or web app that paginates large collections — Pagy's performance advantage over kaminari/will_paginate matters at scale, and its minimal API keeps pagination logic clean.
Avoid When
You're already using kaminari and migration isn't worth it, you need model-level pagination API compatibility, or you're not on Rails.
Use Cases
- • Paginate agent list API responses with Pagy — @pagy, @agents = pagy(Agent.active.order(created_at: :desc)) in Rails controller; pagy_metadata(@pagy) in JSON response includes count, pages, next/prev page info
- • Cursor-based agent pagination for stable ordering — pagy-keyset extra provides cursor pagination for agent lists that need stable pagination despite inserts/deletes
- • Frontend pagination UI for agent admin portal — pagy_bootstrap_nav(@pagy) renders Bootstrap-styled pagination links for agent management views
- • Elasticsearch agent search pagination — pagy_searchkick(@agents) paginates Elasticsearch search results for agent knowledge base search with Pagy's efficient handling
- • API pagination metadata for agent client SDK — JSON response with pagy_metadata includes total count, items_per_page, next_cursor enabling agent API clients to implement pagination
Not For
- • Non-Rails/Ruby apps — Pagy is Ruby-specific; use other pagination libraries for Python (paginate-py), JavaScript (server-side frameworks), or Java agents
- • Infinite scroll without JavaScript — Pagy provides page-based and cursor pagination; infinite scroll requires JavaScript integration with Pagy's JSON API response format
- • When ActiveRecord Relation pagination is in models — Pagy intentionally avoids model-level pagination; if existing code uses collection.page(n).per(m) model-level API, kaminari or will_paginate may be easier to integrate
Interface
Authentication
Pagination library — no auth concepts.
Pricing
Pagy is MIT licensed, maintained by Domizio Demichelis. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ include Pagy::Backend in controller, not model — Pagy::Backend must be included in ApplicationController; calling pagy() in model context fails; agent controllers must include backend module; include Pagy::Frontend in helpers for view helpers
- ⚠ Pagy::OverflowError on page > last_page — requesting page 100 when only 5 pages exist raises Pagy::OverflowError; rescue in agent controller and redirect to last page or return 404; don't let it propagate as 500
- ⚠ pagy() count query can be expensive — Pagy issues separate COUNT query before fetching page records; for complex agent queries with many JOINs, count query can be slow; override count with pagy(collection, count: cached_count) for performance
- ⚠ Extras must be explicitly required — Pagy features are in extras (pagy/extras/bootstrap, pagy/extras/metadata); not including the extra causes undefined method errors; require in pagy initializer only extras you use for agent UI
- ⚠ Keyset pagination requires unique ordered column — pagy-keyset cursor pagination requires ORDER BY on unique column (id, created_at + id); non-unique order causes inconsistent cursor pagination for agent lists with ties
- ⚠ pagy_metadata JSON format changed in Pagy 7 — Pagy 7+ changed pagy_metadata key names (prev_page → prev, next_page → next); if agent API clients depend on old key names, lock pagy version or update clients when upgrading
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for Pagy.
Scores are editorial opinions as of 2026-03-06.