Pagy

Pagy is the ultimate pagination gem that outperforms the others in each and every benchmark and comparison.

Improvements in v2.0+

Lower ruby requirements (ruby v1.9+ || jruby v1.7+) make Pagy very convenient also on older systems
The i18n internal implementation now includes full dynamic support for multi-language apps, it's ~18x faster and uses ~10x less memory than the i18n gem
The searchkick and elasticsearch_rails extras have been refactored with more and better options
Pagy v2.0+ is even faster and lighter than v1.0+ (see charts below)

Comparison with other gems

The best way to quickly get an idea about Pagy is comparing it to the other well known gems.

The values shown in the charts below have been recorded while each gem was producing the exact same output in the exact same environment. (see the Detailed Gems Comparison)

~ 33x Faster!

~ 26x Lighter!

~ 25x Simpler!

~ 850x More Efficient!

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

Disclaimer

Please, notice that benchmarking and profiling the pagination gems in a working app environment may be a quite a tricky task.

If you compare Pagy in your own app and don't notice much of a difference, your benchmarks are most likely not isolating the pagination code from the rest of your app.

Please check the Benchmarks and Memory Profiles Source for a working example about how to properly compare the gems. Feel free to ask here if you need help.

Features

Straightforward Code

Pagy has a very slim core code of just ~100 lines of simple ruby, organized in 3 flat modules, 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...)
100% of its methods are public API, accessible and overridable right where you use them (no pesky monkey-patching neededneed for )
100% test coverage for core code and extras

Totally Agnostic

The Pagy class doesn't need to know anything about your models, ORM or storage, so it doesn't add any code to them (see why...)
It works with all kinds of collections, even pre-paginated, records, Arrays, JSON data... and just any list, even if you cannot count it (see how...)
Pagy works with the most popular Rack frameworks (Rails, Sinatra, Padrino, ecc.) out of the box (see more...)
It works also with any possible non-Rack environment by just overriding one or two two-lines methods (see more...)

Unlike the other gems

Pagy is very modular and does not load nor execute unnecessary code in your app (see why...)
It works even with collections/scopes that already used limit and offset (see how...)
It works with helpers or 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...)
It also works on legacy systems starting from ruby v1.9+ and jruby v1.7+

Easy to use

You can use Pagy in a quite familiar way:

Paginate your collection in some controller:

@pagy, @records = pagy(Product.some_scope)

Render the navigation links with a super-fast helper in some view:

<%== pagy_nav(@pagy) %>

Or - if you prefer - render the navigation links with a template:

<%== render 'pagy/nav', locals: {pagy: @pagy} %>

(see Quick Start for more details)

Easy to extend

Use the official extras, or write your own in just a few lines. Extras add special options and manage different components, behaviors, Frontend or Backend environments... usually by just requiring them:

Backend Extras

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
searchkick: Paginate Searchkick::Results objects

Frontend Extras

bootstrap: Add nav, responsive and compact helpers for the Bootstrap pagination component
bulma: Add nav, responsive and compact helpers for the Bulma CSS pagination component
foundation: Add nav, responsive and compact helpers for the Foundation pagination component
materialize: Add nav responsive and compact helpers for the Materialize CSS pagination component
plain: Add responsive and compact plain/unstyled helpers
semantic: Add nav, responsive and compact helpers for the Semantic UI CSS pagination component

Feature Extras

i18n: Use the I18n gem instead of the pagy 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
support: Extra support for features like: incremental, infinite, auto-scroll pagination
trim: Remove the page=1 param from the first page link

Alternative components

Besides the classic pagination nav, Pagy offers a few ready to use alternatives like:

compact nav: An alternative UI that combines the pagination feature with the navigation info in one compact element:
responsive nav: On resize, the number of page links adapts in real-time to the available window or container width:

Resources

GoRails Screencast

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

Posts and Tutorials

Migrating from WillPaginate and Kaminari (practical guide)
Pagination with Pagy by Tiago Franco
Stateful Tabs with Pagy by Chris Seelus
Quick guide for Pagy with Sinatra and Sequel by Victor Afanasev
Integrating Pagy with Hanami by Paweł Świątkowski
Detailed Gems Comparison (charts and analysis)
Benchmarks and Memory Profiles Source (Rails app repository)

Docs

Support and Feedback

Chat on Gitter

Please Star and Share!

Pagy is young and needs to be known, and you can really help, even with just a click on the star, or sharing a tweet with friends and colleagues. A big thank you for your support!

Help Wanted

Pagy is a fresh project and your help would be great. If you like it, you have a few options to contribute:

Create an issue if anything should be improved/fixed
Submit a pull request to improve Pagy
Submit some cool extra
Submit your translation if your language is missing from the dictionary files
Write a Tutorial or a "How To" topic

Repository Info

Versioning

Pagy follows the Semantic Versioning 2.0.0. Please, check the Changelog for breaking changes introduced by mayor versions.

Branching

Pagy follows the GitFlow branching model with master and dev.

The master branch is the latest rubygem-published release.

The dev branch is the development branch with the new code that will be merged in the next release.

Expect any other branch to be experimental, force-rebased and/or deleted even without merging.

Pull Requests

Please, use dev as the base branch for your Pull Requests.

Credits

Many thanks to:

Imaginary Cloud, for continually publishing high-interest articles and helping share Pagy through their fantastic blog
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

The gem is available as open source under the terms of the MIT License.

glenbray / pagy