#

Pagy the leaping gem!

Agnostic pagination in plain ruby

We needed a leap version to unequivocally segnaling that it's not just a major version: it's a complete redesign of the legacy code at all levels, usage and API included.

Why 43? Because it's exactly one step beyond "The answer to the ultimate question of life, the Universe, and everything." 😉

This version introduces several enhancements, such as new pagination techniques like Keynav and improved automation and configuration processes, reducing setup requirements by 99%. The update also includes a simpler API and new interactive development tools, making it a comprehensive upgrade from previous versions.

• New Keynav Pagination
  • The pagy-exclusive technique using the fastest keyset pagination alongside all frontend helpers.
• New interactive dev-tools
  • New PagyWand to integrate the pagy CSS with your app's themes.
  • New Pagy AI available inside docs and your own app.
• Intelligent automation
  • Configuration requirements reduced by 99%.
  • Simplified JavaScript setup.
  • Automatic I18n loading.
• Simpler API
  • You solely need the pagy method and the @pagy instance to paginate any collection and use any navigation tag and helper.
  • Methods are autoloaded only if used, and consume no memory otherwise.
  • Methods have narrower scopes and can be overridden without deep knowledge.
• New documentation
  • Very concise, straightforward, and easy to navigate and understand.

Take a look at the Examples for a quick overview of the new API.

• Compatible with all environments and collection types
• It can use OFFSET, COUNTLESS, KEYSET, KEYNAV, CALENDAR pagination techniques
• It supports server-side rendering or faster client-side rendering for popular CSS frameworks and APIs.
• It autoloads ONLY the methods that you actually use, with almost zero config
• It boasts 100% test coverage for Ruby, HTML, and JavaScript end-to-end (E2E)

# Include pagy in your code (usually application_controller.rb)
include Pagy::Method

# Offset-based pagination
@pagy, @records = pagy(:offset, Product.all)

# Keyset-based pagination (fastest technique)
@pagy, @records = pagy(:keyset, Product.order(my_order).all)

# Paginate your collection with one of several paginators
@pagy, @records = pagy(...)

See all the available paginators

# JSON:API nested query string. E.g.: ?page[number]=2&page[size]=100
@pagy, @records = pagy(:offset, Product.all, jsonapi: true)
@pagy, @records = pagy(:keyset, Product.order(my_order).all, jsonapi: true)
render json: { links: @pagy.urls_hash, data: @records }

render json: { pagy: @pagy.data_hash, data: @records }

# Extend your models (e.g. application_record.rb)
extend Pagy::Search

# Paginate with pagy:
search           = Product.pagy_search(params[:q])
@pagy, @response = pagy(:elasticsearch_rails, search)
@pagy, @results  = pagy(:meilisearch, search)
@pagy, @results  = pagy(:searchkick, search)

# Or get pagy from paginated results:
@results = Product.search(params[:q])
@pagy    = pagy(:elasticsearch_rails, @results)
@pagy    = pagy(:meilisearch, @results)
@pagy    = pagy(:searchkick, @results)

Combines time-range and offset pagination.

(Available time units: year, quarter, month, week, and day)

@calendar, @pagy, @records = pagy(:calendar, collection, year: {}, month: {}, offset: {})

<%== @calendar[:year].series_nav(:bootstrap) %>
<%== @calendar[:month].series_nav(:bootstrap) %>
<%== @pagy.info_tag %>
...
<%== @pagy.series_nav(:bootstrap) %>

Default :pagy, :bootstrap and :bulma styles shown.

<!-- Render client side nav bar helpers with different html and styles -->
<%== @pagy.series_nav %> <!-- pagy style -->
<%== @pagy.series_nav(:bootstrap) %>
<%== @pagy.series_nav(:bulma) %>

# pagy.rb initializer
javascript_dir = Rails.root.join('app/javascripts')
Pagy.sync_javascript(javascript_dir, 'pagy.mjs') if Rails.env.development?

Faster and responsive

Dynamically fills the container width.

<!-- Render client side nav bar helpers with different html and styles -->
<%== @pagy.series_nav_js %> <!-- pagy style -->
<%== @pagy.series_nav_js(:bootstrap) %>
<%== @pagy.series_nav_js(:bulma) %>

Fastest! Combines navigation and info in minimum space.

<!-- Render client side nav inout helpers with different html and styles -->
<%== @pagy.input_nav_js %> <!-- pagy style -->
<%== @pagy.input_nav_js(:bootstrap) %>
<%== @pagy.input_nav_js(:bulma) %>

Integrate pagy with your app's themes interactively, and ask specific questions right in your app! You need only a single line in your page/layout head to get the Pagy Wand and the Pagy AI:

<%== Pagy.dev_tools %>

• Quick Start
• How To (quick recipes)
• Migrate from WillPaginate and Kaminari (practical guide)
• Discussions
• Issues
• Changelog

Special thanks to:

• Ben Koshy for his contributions to the documentation, user support and interaction with external frameworks
• JetBrains for their free OpenSource license.
• The Stargazers for showing their support

MIT