• Stars
    star
    4,465
  • Rank 9,573 (Top 0.2 %)
  • Language
    Ruby
  • License
    MIT License
  • Created almost 7 years ago
  • Updated 6 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

🏆 The Best Pagination Ruby Gem 🥇

Pagy

Gem Version ruby Build Status Coverage Rubocop Status MIT license CII Best Practices Commits Downloads Stars

🏆 The Best Pagination Ruby Gem 🥇


✴ What's new in 8.0+ ✴

  • WARNING: We may drop pagy's less used CSS extras.
    If you wish to keep them alive, please, vote here
  • New Pagy Playground to showcase, clone and develop pagy APPs without any setup on your side (try the pagy demo)
  • New :max_pages variable to limit the pagination regardless the actual count
  • Better frontend helpers
  • See the Changelog for possible breaking changes

🚀 🚀 🚀 🚀 🚀

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.

Notice: the above charts refers to the comparison of the basic pagy v3.0.0 helper with will_paginate v3.1.7 and kaminari v1.1.1.

While it's not up-to-date, you can expect roughly similar results with the latest versions, maybe a bit less dramatic in performance due to the multiple features added to pagy since v3 (e.g. customizable and translated aria-labels). However, consider that the difference become A LOT bigger in favor of pagy if you use *nav_js helpers, Pagy::Countless or JSON and client side pagination that are not part of the comparison because missing in the other gems.

See the Detailed Gems Comparison for full details.


🤩 It does it all. Better.

Code Structure

  • Pagy has a very slim core code very easy to understand and use.
  • 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
  • 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 ( see why...)_
  • It doesn't impose limits even with collections|scopes that already used limit and offset ( see how...)
  • It raises 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

😎 It's easy to use and customize

Code for basic pagination...
# 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)

Optionally set your defaults in the pagy initializer:

# 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
# Better user experience handled automatically
require 'pagy/extras/overflow'
Pagy::DEFAULT[:overflow] = :last_page
<%# Render a view helper in your views (skipping nav links for empty pages) %>
<%== pagy_nav(@pagy) if @pagy.pages > 1 %>

Or, choose from the following view helpers:

View Helper Name Preview (Bootstrap Style shown)
pagy_nav(@pagy) pagy_nav
pagy_nav_js(@pagy) pagy_nav_js
pagy_info(@pagy) pagy_info
pagy_combo_nav_js(@pagy) pagy_combo_nav_js
pagy_items_selector_js pagy_items_selector_js
pagy_nav(@calendar[:year])
pagy_nav(@calendar[:month])
(other units: :quarter, :week, :day and custom)
calendar extra

(See the 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 all the CSS Framework Extras)

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 all the Search Extras)

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 all the Backend Tools)

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 all the Backend Tools)

Customization for JSON:API pagination...
# Require the jsonapi extra in the pagy initializer
require 'pagy/extras/jsonapi'

# Use it in your actions
pagy, records = pagy(Product.all)
render json: { data:  records,
               links: pagy_jsonapi_links(pagy) }
# besides the query params will be nested. E.g.: ?page[number]=2&page[size]=100

(See all the Backend Tools)

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: Provides better performance of grouped ActiveRecord collections
  • array: Paginate arrays efficiently.
  • calendar: Add pagination filtering by calendar time unit (year, quarter, month, week, day, custom)
  • 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
  • jsonapi: Implement the JSON:API specifications for 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

Extra Features and Tools

  • Pagy::Console: Use pagy in the irb/rails console even without any app nor configuration
  • gearbox: Automatically change the number of items per page depending on the page number
  • i18n: Use the I18n gem instead of the faster pagy-i18n implementation
  • items: Allow the client to request a custom number of items per page with an optional selector UI
  • overflow: Allow easy handling of overflowing pages
  • standalone: Use pagy without any request object, nor Rack environment/gem, nor any defined params method
  • trim: Remove the page=1 param from the first page link

See also the How To Page

🤓 It's well documented and supported

Documentation

Support

Posts and tutorials

Screencasts


Top 💯 Contributors


👏 Credits

Many thanks to:

📦 Repository Info

How to contribute
  • Pull Requests are welcome!
  • Please base your PR against the master branch.
  • For simple contribution you can quickly check your changes with one of the apps in the Pagy Playground and/or the Pagy::Console.
  • If you Create A Pull Request, please ensure that the "All checks have passed" indicator gets green light on the Pull Request page (if it's not enabled, a maintainer will enable it for you).
Versioning
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 internal, experimental, force-pushed, rebased and/or deleted even without merging.

💞 Related Projects

Search rubygems.org

📃 License

MIT

More Repositories

1

flex

The ultimate ruby client for elasticsearch.
Ruby
72
star
2

irt

Interactive Ruby Tools - Improved irb and rails console with a lot of easy and powerful tools.
Ruby
27
star
3

prompter

Makes your prompts easier to build and nicer to look.
Ruby
8
star
4

pagination-comparison

CSS
7
star
5

fm

A complete File Manager for any shell
Shell
6
star
6

dryml-firemarker

Adds DRYML markers viewable with FireMarker (a Firefox/Firebug extension)
Ruby
5
star
7

pagy-extras

Discontinued gem, now integrated in Pagy
Ruby
3
star
8

fav

zsh/fzf plugin that makes it really easy to add and recall named favorites of your important directories
Shell
3
star
9

rematch

Declutter your test files from large hardcoded data and update them automatically when your code changes
Ruby
3
star
10

firemarker

Displays meta info embedded in HTML comments in Firebug
JavaScript
2
star
11

rakext

lite and powerful rake extension
Ruby
1
star
12

gemy

Simple CLI tool useful for gem authors: it eases installing your gem locally, and pushing it to RubyGems.
Ruby
1
star
13

colorer

Easy ANSI code coloring for strings in applications
Ruby
1
star
14

flex-persistence

This is a deprecated gem: please use flex-models.
Ruby
1
star
15

flex-find

This is a deprecated gem: please use flex-scopes
Ruby
1
star
16

flex-backup

This is a deprecated gem: please use flex-admin.
Ruby
1
star
17

flex-rails

Rails integration for Flex
Ruby
1
star
18

flex-scopes

ActiveRecord-like chainable scopes and finders for Flex.
Ruby
1
star
19

dye

Easy ANSI code coloring for strings in libraries
Ruby
1
star
20

flex-admin

Dump/load/rename/live-redindex one or more elasticsearch indices and types.
Ruby
1
star
21

flex-models

Transparently integrates your models with one or more elasticsearch indices.
Ruby
1
star