/pagy-1

The ultimate pagination ruby gem

Primary LanguageRubyMIT LicenseMIT

Pagy

Gem Version ruby Build Status CodeCov Rubocop Status MIT license CII Best Practices Commits Downloads Chat

🤠 The kick-ass pagination gem!

~ 40x Faster!

IPS Chart

~ 36x Lighter!

Memory Chart

~ 35x Simpler!

Objects Chart

~ 1,410x More Efficient!

Resource Consumption Chart

Each dot in the visualization above represents the resources that Pagy consumes for one full rendering. The other gems consume hundreds of times as much for the same rendering.

The IPS/Kb ratio is calculated out of speed (IPS) and Memory (Kb): it shows how well each gem uses each Kb of memory it allocates/consumes.

See the Detailed Gems Comparison for full details.

🤩 It does it all. Better.

Code Structure

  • Pagy has a very slim core code very easy to understand and use (see more...)
  • It has a quite fat set of optional extras that you can explicitly require for very efficient and modular customization (see extras)
  • It has no dependencies: it produces its own HTML, URLs, i18n with its own specialized and fast code (see why...)
  • Its methods are accessible and overridable right where you use them (no pesky monkey-patching needed)

Unlike the other gems

  • Pagy is very modular and does not load any unnecessary code in your app (see why...)
  • It doesn't impose limits on your code even with collections|scopes that already used limit and offset (see how...)
  • It works with fast helpers OR easy to edit templates (see more...)
  • It raises real Pagy::OverflowError exceptions that you can rescue from (see how...) or use the overflow extra for a few ready to use common behaviors
  • It does not impose any difficult-to-override logic or output (see why...)

Better Components

Besides the classic pagination offered by the pagy_nav helpers, you can also use a couple of more performant alternatives:

  • pagy_nav_js: A faster and lighter classic looking UI, rendered on the client side with optional responsiveness:
    bootstrap_nav_js

  • pagy_combo_nav_js: The fastest and lightest alternative UI (48x faster, 48x lighter and 2,270x more efficient than Kaminari) that combines navigation and pagination info in a single compact element:
    bootstrap_combo_nav_js

😎 It's easy to use and customize

Code for basic pagination... 
# Override the pagy default with your own in the pagy initializer...
Pagy::DEFAULT[:items] = 10        # items per page
Pagy::DEFAULT[:size]  = [1,4,4,1] # nav bar links

# In some controller...
include Pagy::Backend

# In some helper...
include Pagy::Frontend

# Wrap your collection with pagy in some action...
@pagy, @records = pagy(Product.my_collection)
# Or override some default only for that instance...
@pagy, @records = pagy(Product.my_collection, items: 15)
<%# Render the navigation bar in some view with a fast helper... %>
<%== pagy_nav(@pagy) %>

<%# Or render it with your own template... %>
<%== render partial: 'pagy/my_nav', locals: {pagy: @pagy} %>

(See Quick Start)

Code for CSS frameworks... 
# Require a CSS framework extra in the initializer (e.g. bootstrap)...
require 'pagy/extras/bootstrap'
<%# Use it in some view in place of the unstyled helper... %>
<%== pagy_bootstrap_nav(@pagy) %>

(See the bootstrap extra)

Code for special collections... 
# Require a backend extra in the initializer (e.g. elasticsearch_rails)...
require 'pagy/extras/elasticsearch_rails'

# In some model...
extend Pagy::ElasticsearchRails

# In some action...
response         = Article.pagy_search(params[:q])
@pagy, @response = pagy_elasticsearch_rails(response)

(See the elasticsearch_rails extra)

Code for client-side|JSON rendering... 
# Require the metadata extra in the initializer...
require 'pagy/extras/metadata'

# in some action...
pagy, records = pagy(Product.all)
render json: { data: records,
               pagy: pagy_metadata(pagy, ...) }

(See the metadata extra)

Code for headers pagination for APIs... 
# Require the headers extra in the initializer...
require 'pagy/extras/headers'

# in some action...
pagy, records = pagy(Product.all)
pagy_headers_merge(pagy)
render json: records

(See the headers extra)

List of all the extras...

Extras add special options and manage different components, behaviors, Frontend or Backend environments... usually by just requiring them (and optionally overriding some default).

Backend Extras

  • arel: Better performance of grouped ActiveRecord collections
  • array: Paginate arrays efficiently, avoiding expensive array-wrapping and without overriding
  • countless: Paginate without the need of any count, saving one query per rendering
  • elasticsearch_rails: Paginate ElasticsearchRails response objects
  • headers: Add RFC-8288 compliant http response headers (and other helpers) useful for API pagination
  • meilisearch: Paginate Meilisearch results
  • metadata: Provides the pagination metadata to Javascript frameworks like Vue.js, react.js, etc.
  • searchkick: Paginate Searchkick::Results objects

Frontend Extras

Extra Features and Tools

  • Pagy::Console: Try any pagy feature or helper right in the irb/rails console even without any app or config
  • gearbox: Automatically change the number of items per page depending on the page number
  • i18n: Use the I18n gem instead of the pagy-i18n implementation
  • items: Allow the client to request a custom number of items per page with an optional selector UI
  • overflow: Allow for easy handling of overflowing pages
  • standalone: Use pagy without any request object, nor Rack environment/gem, nor any defined params method
  • support: Extra support for features like: incremental, auto-incremental and infinite pagination
  • trim: Remove the page=1 param from the first page link

See also the How To Page

🤓 It's very well documented and supported

Watch some great screencast...

GoRails Screencast

GoRails Screencast

Notice: the pagy_nav_bootstrap helper used in the screencast has been renamed as pagy_bootstrap_nav since version 2.0

Mike Rogers Screencast

How To Paginate A Collection Using Pagy

SupeRails Screencast

Ruby on Rails #19 gem Pagy - Ultimate Guide

Raul Palacio Screencast (Spanish)

Raul Palacio Screncast

Read some interesting post and tutorial...
Read the documentation...
Ask for support...

📦 Repository Info

What's new in 5.0
  • This version requires ruby 2.5+. For ruby <2.5 use pagy 3+ (see the pagy3 branch)
  • New: added gearbox extra to automatically change the number of items depending on the page number.
  • Removed support for 4.0 deprecations (see the Changelog)
  • Big code restyling with improved performance, readability and rubocop compliance.
How to contribute
  • Pull Requests are welcome!
  • For simple contribution you can quickly check your changes with the Pagy::Console or with the single file pagy_standalone_app.ru.
  • For more complex contributions you can use the docker development environment or your own environment of course.
  • If you Create A Pull Request, please ensure that the "All checks have passed" indicator gets green light on the Pull Request page. That means that the tests passed and Codecov and Rubocop are happy.
Versioning
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 experimental, force-pushed, rebased and/or deleted even without merging.

💞 Related Projects

  • pagy-cursor An early stage project that implements cursor pagination for AR
  • grape-pagy Pagy pagination for the grape API framework

👏 Credits

Many thanks to:

📃 License

This project is available as open source under the terms of the MIT License.