Skip to content
The ultimate pagination ruby gem
Branch: master
Clone or download
Latest commit 3eacc8d Mar 21, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs better doc examples Mar 21, 2019
gemfiles update travis setup Mar 9, 2019
lib release 2.1.3 Mar 20, 2019
test added Current-Page default header to headers extra Mar 15, 2019
.gitignore
.rubocop.yml replaced efficiency table with resource-consumption chart; other mino… Mar 5, 2019
.travis.yml
CHANGELOG.md release 2.1.3 Mar 20, 2019
Gemfile small improvement for the headers extra doc Mar 16, 2019
Gemfile.lock
LEGACY_CHANGELOG.md fix compilant > compliant typos in docs Mar 15, 2019
LICENSE.txt Fix typo in class name (#122) Feb 5, 2019
README.md lighter README and a few docs improvements Mar 18, 2019
Rakefile
pagy.gemspec setup for ruby 1.9+ and jruby 1.7+ Feb 22, 2019

README.md

Pagy

Gem Version ruby jruby Build Status MIT license Commits Downloads Chat

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
  • Added RFC-8288 compliant http response headers extra
  • 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!

IPS Chart

~ 26x Lighter!

Memory Chart

~ 25x Simpler!

Objects Chart

~ 850x More Efficient!

Resource Consumption Chart

Each dot in the chart 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.

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 needed)
  • 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 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...)
  • 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 customize

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

Feature Extras

  • headers: Add RFC-8288 compliant http response headers (and other helpers) useful for API pagination
  • 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
  • support: Extra support for features like: incremental, auto-incremental and infinite 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:
    pagy-compact

  • responsive nav: A classic looking UI that fits the number of page links to the available width on the client-side:
    pagy-responsive

Resources

GoRails Screencast

Objects Chart

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

Posts and Tutorials

Docs

Support and Feedback

Chat on Gitter

Repository Info

Versioning

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

Branches

The master branch is the latest rubygem-published release. It also contains docs and comment changes that don't affect the published code.

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.

Credits

Many thanks to:

License

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

You can’t perform that action at this time.