[](https://rubygems.org/gems/pagy)
[](https://endoflife.date/ruby)
[](https://github.com/ddnexus/pagy/actions/workflows/api-test.yml)
[](https://github.com/ddnexus/pagy/actions/workflows/e2e-test.yml)
[](http://opensource.org/licenses/MIT)
[](https://github.com/ddnexus/pagy/commits/master/)
[](https://rubygems.org/gems/pagy)
[](https://github.com/ddnexus/pagy/stargazers)
[](https://gurubase.io/g/pagy)
#
Pagy the leaping gem!
_Agnostic pagination in plain ruby_
> [!TIP]
> ⭐ If you like Pagy, please support it with a Star! ⭐
### Version 43
We needed a leap version to unequivocally signal that it's not just a major version: it's a complete redesign of the legacy code at all levels, usage and API included.
**Why 43?** Because it's exactly one step beyond _"The answer to the ultimate question of life, the Universe, and everything."_ 😉
#### Improvements
This version introduces several enhancements, such as new `:countish` and `:keynav_js` paginators and improved automation and configuration processes, reducing setup requirements by 99%. The update also includes a simpler API and new interactive development tools, making it a comprehensive upgrade from previous versions.
- **New [:countish](https://ddnexus.github.io/pagy/toolbox/paginators/countish) Paginator**
- Faster than OFFSET and supporting the full UI
- **New [Keynav](https://ddnexus.github.io/pagy/toolbox/paginators/keynav_js) Pagination**
- The pagy-exclusive technique using the fastest [keyset](https://ddnexus.github.io/pagy/toolbox/paginators/keyset) pagination alongside all frontend helpers.
- **New interactive dev-tools**
- New [PagyWand](https://ddnexus.github.io/pagy/resources/stylesheets/#pagy-wand) to integrate the pagy CSS with your app themes.
- New **Pagy AI** available right inside your own app.
- **Intelligent automation**
- [Configuration](https://ddnexus.github.io/pagy/toolbox/configuration/initializer) requirements reduced by 99%.
- Simplified [JavaScript](https://ddnexus.github.io/pagy/resources/javascript) setup.
- Automatic [I18n](https://ddnexus.github.io/pagy/resources/i18n) loading.
- **[Simpler API](https://github.com/ddnexus/pagy#examples)**
- You solely need the [pagy](https://ddnexus.github.io/pagy/toolbox/paginators) method and the [@pagy](https://ddnexus.github.io/pagy/toolbox/helpers) instance to paginate any collection and use any navigation tag and helper.
- Methods are autoloaded only if used, and consume no memory otherwise.
- Methods have narrower scopes and can be [overridden](https://ddnexus.github.io/pagy/guides/how-to#override-pagy-methods) without deep knowledge.
- **New [documentation](https://ddnexus.github.io/pagy/guides/quick-start)**
- Very concise, straightforward, and easy to navigate and understand.
### Upgrade to 43
See the [Upgrade Guide](https://ddnexus.github.io/pagy/guides/upgrade-guide/)
Take a look at the [Examples](#-examples) for a quick overview of the new API.
### 💚 v3 was already quite snappy...
[
](https://ddnexus.github.io/pagination-comparison/gems.html#ips-benchmark)
[
](https://ddnexus.github.io/pagination-comparison/gems.html#memory-profile)
[
](https://ddnexus.github.io/pagination-comparison/gems.html#memory-profile)
[
](https://ddnexus.github.io/pagination-comparison/gems.html#efficiency-ratio)
### ... and now it's more, with less.
- Compatible with all environments and collection types
- It can use OFFSET, COUNTISH, COUNTLESS, KEYSET, KEYNAV, SEARCH, CALENDAR, pagination techniques
- It supports server-side rendering or faster client-side rendering for popular CSS frameworks and APIs
- It autoloads ONLY the methods that you actually use, with almost zero configuration
- It boasts 100% test coverage for Ruby, HTML, and JavaScript end-to-end (E2E)
> [!TIP]
> ⭐ If you like Pagy, please support it with a Star! ⭐
### 💚 Examples
##### Pagination code
```rb
# Include pagy in your code (usually application_controller.rb)
include Pagy::Method
# Offset-based pagination
@pagy, @records = pagy(:offset, Product.all)
# Keyset-based pagination (fastest technique)
@pagy, @records = pagy(:keyset, Product.order(my_order).all)
# Paginate your collection with one of several paginators
@pagy, @records = pagy(...)
```
_See all the available [paginators](https://ddnexus.github.io/pagy/toolbox/paginators/#paginators)_
##### JSON:API pagination
```ruby
# JSON:API nested query string. E.g.: ?page[number]=2&page[size]=100
@pagy, @records = pagy(:offset, Product.all, jsonapi: true)
@pagy, @records = pagy(:keyset, Product.order(my_order).all, jsonapi: true)
render json: { links: @pagy.urls_hash, data: @records }
```
##### JSON-client pagination
```ruby
render json: { pagy: @pagy.data_hash, data: @records }
```
##### Search server pagination
Available paginators: `:elasticsearch_rails`, `:meilisearch`, `:searchkick`, `:typesense_rails`
```rb
# Extend your models (e.g. application_record.rb)
extend Pagy::Search
# Paginate with pagy:
search = Product.pagy_search(params[:q])
@pagy, @response = pagy(:a_search_paginator, search)
# Or get pagy from paginated results:
@results = Product.search(params[:q])
@pagy = pagy(:a_search_paginator, @results)
```
##### Calendar pagination
Combine `time-range` and `offset` pagination.
_(Available time units: year, quarter, month, week, and day)_
```ruby
@calendar, @pagy, @records = pagy(:calendar, collection, year: {}, month: {}, offset: {})
```
```ERB
<%== @calendar[:year].series_nav(:bootstrap) %>
<%== @calendar[:month].series_nav(:bootstrap) %>
<%== @pagy.info_tag %>
...
<%== @pagy.series_nav(:bootstrap) %>
```
##### Server side rendering
##### `series_nav`
Default `:pagy`, `:bootstrap` and `:bulma` styles shown.
```erb
<%== @pagy.series_nav %>
<%== @pagy.series_nav(:bootstrap) %>
<%== @pagy.series_nav(:bulma) %>
```
##### Client side rendering
```rb
# pagy.rb initializer
javascript_dir = Rails.root.join('app/javascripts')
Pagy.sync_javascript(javascript_dir, 'pagy.mjs') if Rails.env.development?
```
##### `series_nav_js`
**Faster and responsive**
Dynamically fills the container width.
```erb
<%== @pagy.series_nav_js %>
<%== @pagy.series_nav_js(:bootstrap) %>
<%== @pagy.series_nav_js(:bulma) %>
```
##### `input_nav_js`
**Fastest!** Combines navigation and info in minimum space.
```erb
<%== @pagy.input_nav_js %>
<%== @pagy.input_nav_js(:bootstrap) %>
<%== @pagy.input_nav_js(:bulma) %>
```
### 💚 Dev Tools
Integrate pagy with your app's themes interactively ([watch demo](https://youtu.be/GhhNRrVG9jg)), and ask specific questions to the Pagy AI __right in your app__! You need only a single line in your page/layout `head` to get the Pagy Wand and the Pagy AI:
```erb
<%== Pagy.dev_tools %>
```
See [Dev Tools](https://ddnexus.github.io/pagy/sandbox/dev_tools/)
### 💚 Support and Docs
- [Quick Start](https://ddnexus.github.io/pagy/guides/quick-start)
- [How To (quick recipes)](https://ddnexus.github.io/pagy/guides/how-to/)
- [Migrate from WillPaginate and Kaminari](https://ddnexus.github.io/pagy/guides/migration-guide) (practical guide)
- [Discussions](https://github.com/ddnexus/pagy/discussions/categories/q-a)
- [Issues](https://github.com/ddnexus/pagy/issues)
- [Changelog](https://ddnexus.github.io/pagy/changelog)
> [!TIP]
> ⭐ If you like Pagy, please support it with a Star! ⭐
### Top 💯 Contributors
[
](https://github.com/ddnexus/pagy/commits?author=ddnexus)[
](https://github.com/ddnexus/pagy/commits?author=benkoshy)[
](https://github.com/ddnexus/pagy/commits?author=grosser)[
](https://github.com/ddnexus/pagy/commits?author=Earlopain)[
](https://github.com/ddnexus/pagy/commits?author=workgena)[
](https://github.com/ddnexus/pagy/commits?author=djpremier)[
](https://github.com/ddnexus/pagy/commits?author=bquorning)[
](https://github.com/ddnexus/pagy/commits?author=molfar)[
](https://github.com/ddnexus/pagy/commits?author=sunny)[
](https://github.com/ddnexus/pagy/commits?author=enzinia)[
](https://github.com/ddnexus/pagy/commits?author=espen)[
](https://github.com/ddnexus/pagy/commits?author=berniechiu)[
](https://github.com/ddnexus/pagy/commits?author=renshuki)[
](https://github.com/ddnexus/pagy/commits?author=7a6163)[
](https://github.com/ddnexus/pagy/commits?author=jyuvaraj03)[
](https://github.com/ddnexus/pagy/commits?author=wimdavies)[
](https://github.com/ddnexus/pagy/commits?author=tiagotex)[
](https://github.com/ddnexus/pagy/commits?author=gamafranco)[
](https://github.com/ddnexus/pagy/commits?author=thomasklemm)[
](https://github.com/ddnexus/pagy/commits?author=tersor)[
](https://github.com/ddnexus/pagy/commits?author=kelso)[
](https://github.com/ddnexus/pagy/commits?author=simonneutert)[
](https://github.com/ddnexus/pagy/commits?author=747)[
](https://github.com/ddnexus/pagy/commits?author=ashmaroli)[
](https://github.com/ddnexus/pagy/commits?author=benjaminwols)[
](https://github.com/ddnexus/pagy/commits?author=excid3)[
](https://github.com/ddnexus/pagy/commits?author=cseelus)[
](https://github.com/ddnexus/pagy/commits?author=claudiob)[
](https://github.com/ddnexus/pagy/commits?author=sabljak)[
](https://github.com/ddnexus/pagy/commits?author=jeffse)[
](https://github.com/ddnexus/pagy/commits?author=petergoldstein)[
](https://github.com/ddnexus/pagy/commits?author=rainerborene)[
](https://github.com/ddnexus/pagy/commits?author=yenshirak)[
](https://github.com/ddnexus/pagy/commits?author=rbngzlv)[
](https://github.com/ddnexus/pagy/commits?author=woller)[
](https://github.com/ddnexus/pagy/commits?author=WilliamHorel)[
](https://github.com/ddnexus/pagy/commits?author=okuramasafumi)[
](https://github.com/ddnexus/pagy/commits?author=olieidel)[
](https://github.com/ddnexus/pagy/commits?author=olleolleolle)[
](https://github.com/ddnexus/pagy/commits?author=PedroAugustoRamalhoDuarte)[
](https://github.com/ddnexus/pagy/commits?author=pedrocarmona)[
](https://github.com/ddnexus/pagy/commits?author=peter50216)[
](https://github.com/ddnexus/pagy/commits?author=rafaeelaudibert)[
](https://github.com/ddnexus/pagy/commits?author=rafaelmontas)[
](https://github.com/ddnexus/pagy/commits?author=rogermarlow)[
](https://github.com/ddnexus/pagy/commits?author=RyanTG)[
](https://github.com/ddnexus/pagy/commits?author=Tolchi)[
](https://github.com/ddnexus/pagy/commits?author=artplan1)[
](https://github.com/ddnexus/pagy/commits?author=sk8higher)[
](https://github.com/ddnexus/pagy/commits?author=muhammadnawzad)[
](https://github.com/ddnexus/pagy/commits?author=ronald)[
](https://github.com/ddnexus/pagy/commits?author=achmiral)[
](https://github.com/ddnexus/pagy/commits?author=mikepayready)[
](https://github.com/ddnexus/pagy/commits?author=mcauser)[
](https://github.com/ddnexus/pagy/commits?author=mauro-ni)[
](https://github.com/ddnexus/pagy/commits?author=borama)[
](https://github.com/ddnexus/pagy/commits?author=creativetags)[
](https://github.com/ddnexus/pagy/commits?author=mcary)[
](https://github.com/ddnexus/pagy/commits?author=marckohlbrugge)[
](https://github.com/ddnexus/pagy/commits?author=fluser)[
](https://github.com/ddnexus/pagy/commits?author=maful)[
](https://github.com/ddnexus/pagy/commits?author=LuukvH)[
](https://github.com/ddnexus/pagy/commits?author=AngelGuerra)[
](https://github.com/ddnexus/pagy/commits?author=tr4b4nt)[
](https://github.com/ddnexus/pagy/commits?author=tiejianluo)[
](https://github.com/ddnexus/pagy/commits?author=szTheory)[
](https://github.com/ddnexus/pagy/commits?author=smoothdvd)[
](https://github.com/ddnexus/pagy/commits?author=rhodes-david)[
](https://github.com/ddnexus/pagy/commits?author=radinreth)[
](https://github.com/ddnexus/pagy/commits?author=pranavbabu)[
](https://github.com/ddnexus/pagy/commits?author=okliv)[
](https://github.com/ddnexus/pagy/commits?author=nedimdz)[
](https://github.com/ddnexus/pagy/commits?author=msdundar)[
](https://github.com/ddnexus/pagy/commits?author=m-abdurrehman)[
](https://github.com/ddnexus/pagy/commits?author=ethancrawford)[
](https://github.com/ddnexus/pagy/commits?author=dwieringa)[
](https://github.com/ddnexus/pagy/commits?author=YutoYasunaga)[
](https://github.com/ddnexus/pagy/commits?author=fkmy)[
](https://github.com/ddnexus/pagy/commits?author=iamyujinwon)[
](https://github.com/ddnexus/pagy/commits?author=yhk1038)[
](https://github.com/ddnexus/pagy/commits?author=ya-s-u)[
](https://github.com/ddnexus/pagy/commits?author=yshmarov)[
](https://github.com/ddnexus/pagy/commits?author=Davidzhu001)[
](https://github.com/ddnexus/pagy/commits?author=thattimc)[
](https://github.com/ddnexus/pagy/commits?author=thomaschauffour)[
](https://github.com/ddnexus/pagy/commits?author=snkashis)[
](https://github.com/ddnexus/pagy/commits?author=sliminas)[
](https://github.com/ddnexus/pagy/commits?author=ShyamBorsaniya)[
](https://github.com/ddnexus/pagy/commits?author=serghost)[
](https://github.com/ddnexus/pagy/commits?author=loed-idzinga)[
](https://github.com/ddnexus/pagy/commits?author=gjtorikian)[
](https://github.com/ddnexus/pagy/commits?author=tulak)[
](https://github.com/ddnexus/pagy/commits?author=Federico-G)[
](https://github.com/ddnexus/pagy/commits?author=egimenos)[
](https://github.com/ddnexus/pagy/commits?author=elliotlarson)[
](https://github.com/ddnexus/pagy/commits?author=hungdiep97)[
](https://github.com/ddnexus/pagy/commits?author=Cosmo)[
](https://github.com/ddnexus/pagy/commits?author=davidwessman)[
](https://github.com/ddnexus/pagy/commits?author=david-a-wheeler)[
](https://github.com/ddnexus/pagy/commits?author=daniel-rikowski)
### 💚 Credits
Special thanks to:
- [JetBrains](http://www.jetbrains.com?from=https%3A%2F%2Fgithub.com%2Fddnexus%2Fpagy) for their free OpenSource license.
- [Ben Koshy](https://github.com/benkoshy) for his contributions to the documentation, user support and interaction with external frameworks.
- [The Stargazers](https://github.com/ddnexus/pagy/stargazers) for their support.
### 💚 Repository Info
How to contribute
See [Contributing](https://github.com/ddnexus/pagy/blob/master/.github/CONTRIBUTING.md)
Versioning
- Pagy follows the [Semantic Versioning 2.0.0](https://semver.org/). Please check the [Changelog](https://ddnexus.github.io/pagy/changelog) for breaking changes introduced by major versions. Using [pessimistic version constraint](https://guides.rubygems.org/patterns/#pessimistic-version-constraint) in your Gemfile will ensure smooth upgrades.
Branches
- The `master` branch is the latest rubygem-published release. It also contains docs and comment changes that don't affect the published code. It is never force-pushed.
- The `dev` branch is the development branch with the new code that will be merged in the next release. It could be force-pushed.
- Expect any other branch to be internal, experimental, force-pushed, rebased and/or deleted even without merging.
### 💚 License
[MIT](https://opensource.org/licenses/MIT)