rails-pagination-kaminari

Rails Pagination with Kaminari

Kaminari is a scope and engine-based pagination library that provides a clean, powerful, customizable paginator for Rails applications. It's non-intrusive, chainable with ActiveRecord, and highly customizable.

Quick Setup

# Add to Gemfile
bundle add kaminari

# Generate configuration file (optional)
rails g kaminari:config

# Generate view templates for customization (optional)
rails g kaminari:views default

Basic Usage

Controller Pagination

# app/controllers/posts_controller.rb
class PostsController < ApplicationController
  def index
    @posts = Post.order(:created_at).page(params[:page])
    # Returns 25 items per page by default
  end
end

View Helper

<!-- app/views/posts/index.html.erb -->
<%= paginate @posts %>

That's it! Kaminari automatically adds pagination links.

Core Methods

Page Scope

# Basic pagination
User.page(1)                    # First page, 25 items
User.page(params[:page])        # Dynamic page from params

# Custom per-page
User.page(1).per(50)            # 50 items per page

# Chaining with scopes
User.active.order(:name).page(params[:page]).per(20)

# With associations
User.includes(:posts).page(params[:page])

Pagination Metadata

users = User.page(2).per(20)

users.current_page      #=> 2
users.total_pages       #=> 10
users.total_count       #=> 200
users.limit_value       #=> 20
users.first_page?       #=> false
users.last_page?        #=> false
users.next_page         #=> 3
users.prev_page         #=> 1
users.out_of_range?     #=> false

Configuration

Global Configuration

# config/initializers/kaminari_config.rb
Kaminari.configure do |config|
  config.default_per_page = 25        # Default items per page
  config.max_per_page = 100           # Maximum allowed per page
  config.max_pages = nil              # Maximum pages (nil = unlimited)
  config.window = 4                   # Inner window size
  config.outer_window = 0             # Outer window size
  config.left = 0                     # Left outer window
  config.right = 0                    # Right outer window
  config.page_method_name = :page     # Method name (change if conflicts)
  config.param_name = :page           # URL parameter name
end