Pagy

🏆 The Best Pagination Ruby Gem 🥇

~ 40x Faster!

~ 36x Lighter!

~ 35x Simpler!

~ 1,410x More Efficient!

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.

👍 If you like Pagy, give it a star! ⭐

Thank you for showing your support!

🤩 It does it all. Better.

It works in any environment
With Rack frameworks like Rails, Sinatra, Padrino, ecc. or in pure ruby even without Rack
It works with any collection
With any ORM, any DB, any search gem, elasticsearch_rails, meilisearch, searchkick, ransack, and just any list, even if you cannot count it
It supports all kinds of pagination
calendar, countless, geared, incremental, auto-incremental, infinite, headers, JSON, cursor
It supports all kinds of CSS Frameworks
bootstrap, bulma, foundation, materialize, semantic, uikit, tailwind
It supports faster client-side rendering
With classic or innovative UI components (see Javascript Navs and Javascript Combo Navs) or by serving JSON to your favorite Javascript framework
It has 100% of test coverage for Ruby, HTML and Javascript E2E (see Pagy Workflows CI)

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:
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:

😎 It's easy to use and customize

Code for basic pagination...

# Optionally override some 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

# Include it in the controllers (e.g. application_controller.rb)
include Pagy::Backend

# Include it in the helpers (e.g. application_helper.rb)
include Pagy::Frontend

# Wrap your collections with pagy in your actions
@pagy, @records = pagy(Product.all)

<%# Render the navigation bar in your views %>
<%== pagy_nav(@pagy) %>

(See Quick Start)

Customization for CSS frameworks...

# Require a CSS framework extra in the pagy initializer (e.g. bootstrap)
require 'pagy/extras/bootstrap'

<%# Use it in your views %>
<%== pagy_bootstrap_nav(@pagy) %>

(See the bootstrap extra)

Customization for special collections...

# Require some special backend extra in the pagy initializer (e.g. elasticsearch_rails)
require 'pagy/extras/elasticsearch_rails'

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

# Use it in your actions
response         = Article.pagy_search(params[:q])
@pagy, @response = pagy_elasticsearch_rails(response)

(See the elasticsearch_rails extra)

Customization for client-side|JSON rendering...

# Require the metadata extra in the pagy initializer
require 'pagy/extras/metadata'

# Use it in your actions
pagy, records = pagy(Product.all)
render json: { data: records,
               pagy: pagy_metadata(pagy) }

(See the metadata extra)

Customization for headers pagination for APIs...

# Require the headers extra in the pagy initializer
require 'pagy/extras/headers'

# Use it in your actions
pagy, records = pagy(Product.all)
pagy_headers_merge(pagy)
render json: records

(See the headers extra)

More customization with 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
calendar: Add pagination filtering by calendar time unit (year, quarter, month, week, day)
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

bootstrap: Add nav, nav_js and combo_nav_js helpers for the Bootstrap pagination component
bulma: Add nav, nav_js and combo_nav_js helpers for the Bulma CSS pagination component
foundation: Add nav, nav_js and combo_nav_js helpers for the Foundation pagination component
materialize: Add nav, nav_js and combo_nav_js helpers for the Materialize CSS pagination component
navs: Add nav_js and combo_nav_js unstyled helpers
semantic: Add nav, nav_js and combo_nav_js helpers for the Semantic UI CSS pagination component
tailwind: Extra styles for Tailwind CSS
uikit: Add nav, nav_js and combo_nav_js helpers for the UIkit pagination component

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

🤓 It's very well documented and supported

Read the documentation...

Migrate from WillPaginate and Kaminari (practical guide)
Quick Start
Documentation
Changelog
Deprecations

Ask for support...

Watch some great 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

SupeRails Screencast

Raul Palacio Screencast (Spanish)

Posts and tutorials...

Migrate from WillPaginate and Kaminari (practical guide)
Detailed Gems Comparison (charts and analysis)
Benchmarks and Memory Profiles Source (Rails app repository)
Faster Pagination with Pagy introductory tutorial by Sirajus Salekin
Pagy with Templates Minipost by aloucas
Pagination with Pagy by Tiago Franco
Quick guide for Pagy with Sinatra and Sequel by Victor Afanasev
Integrating Pagy with Hanami by Paweł Świątkowski
Stateful Tabs with Pagy by Chris Seelus
Endless Scroll / Infinite Loading with Turbo Streams & Stimulus by Stefan Wienert
Pagination with Hotwire by Jonathan Greenberg
Pagination and infinite scrolling with Rails and the Hotwire stack by David Colby
Pagination for Beginners: What is it? Why bother? by Ben Koshy.
Handling Pagination When POSTing Complex Search Forms by Ben Koshy.
How to Override pagy methods only in specific circumstances by Ben Koshy.
How to make your pagination links sticky + bounce at the bottom of your page by Ben Koshy.
日本語の投稿
한국어 튜토리얼

📦 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 the calendar extra for pagination filtering by calendar time unit (year, quarter, month, week, day)
New: Added the 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

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 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:

Ben Koshy for his contributions to the documentation, user support and interaction with external frameworks
GoRails for the great Pagy Screencast and their top notch Rails Episodes
Imaginary Cloud for continually publishing high-interest articles and helping to share Pagy when it just started
JetBrains for their free OpenSource license
The Contributors for all the smart code and suggestions merged in the project
The Stargazers for showing their support

📃 License

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

tysongach / pagy Goto Github PK

pagy's Introduction