# Pagy the leaping gem!

# 💚 Version 10

# A complete redesign of the legacy code.

New Keynav Pagination
- The pagy-exclusive technique using keyset pagination alongside all frontend helpers.
Method Autoloading
- Methods are autoloaded only if used, unused methods consume no memory.
Intelligent automation
- Configuration requirements reduced by 99%, simplified JavaScript setup and automatic I18n loading.
Simplified user interaction
- You solely need the pagy method and the @pagy instance, to paginate any collection, and use any navigation tag and helper.
Self-explaining API
- Explicit and unambiguous renaming reduces the need to consult the documentation.
New and simpler documentation
- Very concise, straightforward, easy to navigate and understand.
Effortless overriding
- The new methods have narrower scopes and can be overridden without deep knowledge.

See the CHANGELOG for breaking changes

# 💚 v3 was already quite good...

# 💚 Now it's more... with less

Compatible with all environments and collection types
It can use OFFSET, COUNTLESS, KEYSET, KEYNAV, 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 config
It boasts 100% test coverage for Ruby, HTML, and JavaScript end-to-end (E2E)

# 💚 Examples

# Pagination code

# 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

# JSON:API pagination

# 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.links_hash, data: @records }

# JSON-client pagination

render json: { pagy: @pagy.data_hash, data: @records }

# Search server pagination

# Extend your models (e.g. application_record.rb)
extend Pagy::Search

# Paginate with pagy:
search           = Product.pagy_search(params[:q])
@pagy, @response = pagy(:elasticsearch_rails, search)
@pagy, @results  = pagy(:meilisearch, search)
@pagy, @results  = pagy(:searchkick, search)

# Or get pagy from paginated results:
@results = Product.search(params[:q])
@pagy    = pagy(:elasticsearch_rails, @results)
@pagy    = pagy(:meilisearch, @results)
@pagy    = pagy(:searchkick, @results)

# Server side rendering

<!-- Render nav bar helpers with different styles -->
<%== @pagy.nav_tag %> <!-- default style -->
<%== @pagy.nav_tag(:bootstrap) %>
<%== @pagy.nav_tag(:bulma) %>

# Client side rendering

# pagy.rb initializer
javascript_dir = Rails.root.join('app/javascript')
Pagy.sync_javascript(javascript_dir, 'pagy.mjs') if Rails.env.development?

<!-- Render client side nav bar helpers of different types and styles -->
<%== @pagy.nav_js_tag %> <!-- default style -->
<%== @pagy.nav_js_tag(:bootstrap) %>
<%== @pagy.nav_js_tag(:bulma) %>

<%== @pagy.combo_nav_js_tag %> <!-- default style -->
<%== @pagy.combo_nav_js_tag(:bootstrap) %>
<%== @pagy.combo_nav_js_tag(:bulma) %>

# View helpers

Pagy offers a variety of view helpers for pagination. Below is a list of available UI components, along with their previews ( Bootstrap styling example).

Helper Name	Preview (Bootstrap Style shown)
`@pagy.nav_tag`
`@pagy.nav_js_tag`
`@pagy.info_tag`
`@pagy.combo_nav_js_tag`
`@pagy.limit_selector_js_tag`
`@calendar[:year].nav_tag` `@calendar[:month].nav_tag` (other units: `:quarter`, `:week`, `:day`)

# 💚 Support and Docs

Quick Start
How To (quick recipes)
Migrate from WillPaginate and Kaminari (practical guide)
Discussions
Issues
Changelog

# Top 💯 Contributors

# 💚 Credits

Many thanks to:

Ben Koshy for his contributions to the documentation, user support and interaction with external frameworks
JetBrains for their free OpenSource license project
The Stargazers for showing their support

# 💚 Repository Info

How to contribute

See Contributing

Versioning

Pagy follows the Semantic Versioning 2.0.0. Please, check the Changelog for breaking changes introduced by mayor versions. Using 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