# Quick Start

If you want to just try Pagy before using it in your own app, you have a couple of alternatives...

Try it now!

Run the interactive demo from your terminal:

gem install pagy
pagy demo

...and point your browser to http://0.0.0.0:8000

Interact with every method, helper and extra in a IRB console without any setup:

Terminal
gem install pagy

...and use it without any app

# 1. Install

If you use Bundler, add the gem in the Gemfile, optionally avoiding the next major version with breaking changes ( see RubyGem Specifiers):

Gemfile
gem 'pagy', '~> 9.3' # omit patch digit

If you don't use Bundler, install and require the Pagy gem:

Terminal
gem install pagy

Ruby file
require 'pagy'

# 2. Configure

Download the configuration file linked below and save it into the config/initializers dir

pagy.rb

pagy.rb 9.49KB

Download the configuration file linked below and require it when your app starts

pagy.rb

pagy.rb 9.49KB

Pagy doesn't load unnecessary code in your app!

Uncomment/edit the pagy.rb file in order to explicitly require the extras you need and eventually customize the static Pagy::DEFAULT variables in the same file.

You can further customize the variables per instance, by explicitly passing any variable to the Pagy*.new constructor or to any pagy* backend/controller method.

# 3. Backend Setup

# Include the backend

ApplicationController/AnyController
include Pagy::Backend

# Use the `pagy` method

Controller action
@pagy, @records = pagy(Product.some_scope)

For search backends see: elasticsearch_rails, meilisearch, searchkick, ransack.

You may also use the calendar, countless, geared, incremental, auto-incremental, infinite and keyset pagination

# 4. Render the pagination

Your pagination is rendered on the server

# Include the frontend

ApplicationHelper/AnyHelper
include Pagy::Frontend

# Use a fast helper

View
<%# Note the double equals sign "==" which marks the output as trusted and html safe: %>
<%== pagy_nav(@pagy) %>

# Pick a stylesheet or a CSS framework

For native pagy helpers (used also with tailwind), you can integrate the Pagy Stylesheets
For different CSS frameworks and different helpers (static, responsive, compact, etc.), you can look at the bootstrap, bulma extras

Your pagination is rendered by Vue.js, react.js, ...

# Require the metadata extra

pagy.rb (initializer)
require 'pagy/extras/metadata'

# Add the metadata to your JSON response

Controller action
render json: { data: @records, pagy: pagy_metadata(@pagy, ...) }

Your API is consumed by some client

# Consider using the Keyset pagination

Orders of magnitude faster on big data... see Pagy::Keyset

# Require the headers extra

pagy.rb (initializer)
require 'pagy/extras/headers'

# Add the pagination headers to your responses

Controller
after_action { pagy_headers_merge(@pagy) if @pagy }

# Render your JSON response as usual

Controller action
render json: { data: @records }