Pagy is the ultimate pagination gem that outperforms the others in each and every benchmark and comparison.
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: same environment conditions, same task, just different gems (see the Detailed Gems Comparison)
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 has a very slim core code of just ~100 line 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, pluralization and interpolation 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 need of monkey-patching)
- 100% test coverage for core code and extras
- 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 whatever you can count (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...)
- Pagy is very modular and does not load nor execute unnecessary code in your app (see why...)
- It works with collections/scopes that already used
limit
andoffset
(see how...) - It works with helpers or templates (see more...)
- It raises real
Pagy::OutOfRangeError
exceptions that you can rescue from (see how...) or use the out_of_range extra for a few ready to use common behaviors - It does not impose any difficult-to-override logic or output (see why...)
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)
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:
- array: Paginate arrays efficiently, avoiding expensive array-wrapping and without overriding
- searchkick: Paginate
Searchkick::Results
objects efficiently, avoiding expensive oject-wrapping and without overriding
- bootstrap: Nav helpers and templates for the Bootstrap pagination component
- bulma: Nav helpers and templates for the Bulma CSS pagination component
- foundation: Nav helpers and templates for the Foundation pagination component
- materialize: Nav helpers for the Materialize CSS pagination component
- navs: Responsive and compact generic/unstyled nav helpers
- semantic: Nav helpers for the Semantic UI CSS pagination component
- 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
- out_of_range: Allow for easy handling of out of range pages
- trim: Remove the
page=1
param from the first page link
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:
- 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 analisys)
- Benchmarks and Memory Profiles Source (Rails app repository)
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 collegues. A big thank you for your support!
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
master
is the latest rubygem-published release (plus changes that don't affect the actual gem behavior, e.g. doc, tests). You should use it as the base branch for pull requests, because it will not be force-rebased.
dev
is the development branch that is kept rebased on top of master
, so expect it to be force-rebased (i.e. do not use it as the base for your commits). Use dev
as a preview for trying the new code that will be merged in the next release, but please, don't use it as the base branch for pull requests.
Many thansk 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
The gem is available as open source under the terms of the MIT License.