Pagy Documentation

To use the :searchkick paginator, you must extend the Searchkick module with Pagy::Search. This is typically done in a Pagy initializer file (e.g., pagy.rb).

Searchkick.extend Pagy::Search

You can run a live demonstration of Pagy using the provided sandbox command. This allows you to interact with the library in a running application environment.

bundle exec pagy {{ $.app }}

Pagy Wand is a visual tool that allows you to adjust the appearance of Pagy components in real time.

Key features:

• Control visual aspects using presets and sliders.
• Generate CSS: Once you have achieved the desired look, you can copy and paste the generated "CSS Override" block into your application's stylesheet to persist the changes.
• Help: Click the question mark icon within the Wand interface for assistance.

In version 2.0.0, the Navs extra helpers were renamed and the requirement path changed. The plain_ qualifier was removed from helper names.

Requirement Change: Replace require "pagy/extras/navs" with require "pagy/extras/plain".

Pagy provides two main CSS files for integration. Choose the one that matches your application's styling framework:

1. pagy.css: A general-purpose stylesheet suitable for any application.
2. pagy-tailwind.css: Specifically designed for applications using Tailwind CSS.

Note: If you are using the :bootstrap or :bulma helpers and their corresponding styles, you do not need to include any Pagy stylesheets.

In Passive mode, you perform the search manually using Searchkick's standard methods, and Pagy creates the pagination object from the resulting Searchkick::Results object.

# Controller usage
# Standard results (already paginated via Searchkick)
@results = Article.search('*', page: 1, per_page: 10, ...)

# Get the pagy object out of it
@pagy = pagy(:searchkick, @results, **options)

To use the common pagy interface for all pagination techniques, include Pagy::Method in your controller (typically ApplicationController). This method allows you to paginate any collection using various techniques like :offset or :keyset.

include Pagy::Method

Replace legacy pagination helpers in your views with Pagy's navigation helpers. For example, replace will_paginate @records or paginate @records with a call to the pagy object's navigation method.

<%= will_paginate @records %>
<%= paginate @records %>

<%== @pagy.series_nav %>

To keep your chosen Pagy configuration files (pagy*) in sync with the repository in your local development environment, you can use the Pagy.sync method. This copies the files to your specified directory so they are processed as part of your own application files.

Add the following to your initializer (e.g., pagy.rb):

# Replace 'pagy*' with the file you picked
Pagy.sync({{ $.resource }}, Rails.root.join('{{ $.remote_dir }}'), 'pagy*') if Rails.env.development?

For :keyset pagination to provide performance gains, you must ensure your database is properly indexed:

1. Column Match: The index must include the exact same columns and the exact same ordering direction as your set.
2. Index Type: Use an index type that minimizes data scans, such as a B-tree or B+ Tree.
3. Verification: Use tools like EXPLAIN ANALYZE to confirm that the database is performing an index scan rather than a full table scan.