muhammadyana/pagy

The ultimate pagination ruby gem

Pagy

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

Benchmarks

The best way to quickly get an idea about its features 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: same environment conditions, same task, just different gems (see the complete Gems Comparison)

Pagy is a lot faster

Pagy uses a lot less memory

Pagy is a lot simpler

Pagy is a lot 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.

Pagy does not suffer the typical limitations of the other gems

• it works with collections/scopes that already used limit and offset
• it works with both helpers or templates (your choice)
• it raises real Pagy::OutOfRangeError exceptions that you can rescue from
• it does not impose any difficult-to-override logic or output

Features

Straightforward code

• Pagy is just ~100 lines of simple ruby, organized in 3 flat modules very easy to understand and use
• it produces its own HTML, URLs, pluralization and interpolation with its own specialized and fast code
• 100% of its methods are public API, accessible and overridable right where you use them (no need of monkey patching or subclassing)

Totally agnostic

• it doesn't need to know anything about your models, ORM or Storage, so it doesn't add any code to them
• it works with all kinds of collections, even pre-paginated, records, Arrays, JSON data... and just whatever you can count
• it works with all Rack frameworks (Rails, Sinatra, Padrino, ecc.) out of the box
• it works with any possible non-Rack envoronment by just overriding one or two one-liner methods

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} %>

Easy to extend

Use the official extras contained in the pagy-extras gem, or write your own in just a few lines:

Bootstrap Extra

This extra adds a nav helper and a few templates compatible with the Bootstrap pagination (more info...).

Responsive Extra

This extra adds responsiveness to the pagination UI. The number of page links will adapt in real-time to the available window or container width. Here is an example of how the same pagination nav will look like by resizing the browser window:

(more info...)

Compact Extra

This extra adds an alternative pagination UI that joins the pagination feature with the navigation info in one compact element. It is especially useful for small size screens.

(more info...)

Support, Comments and Feature Requests

Useful Links

• Documentation
• Pagination Comparison App

Help Wanted

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

• write a tutorial or a post or even just a tweet (pagy is young and needs to be known)
• write a "How To" topic (the documentation is covering the basics and there is a lot of space for additions)
• submit some cool extra
• submit a pull request to make pagy even faster, save more memory or improve its usability
• create an issue if anything should be improved/fixed

Branches and Pull Requests

master is the latest rubygem-published release: you should use it as the base branch for pull requests, because it will not be force-rebased. dev is the development branch that will receive your pull requests, and that get merged into master before a new release. Expect dev to be force-rebased, so it's probably wise not to use it as the base for your commits.

License

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