💎 RailsPaginationUltimate

The ultra-premium, high-performance pagination powerhouse for modern Rails applications.

RailsPaginationUltimate is built for developers who need more than just simple page links. It is a feature-rich, "Best-in-Class" replacement for Kaminari and WillPaginate, offering pro-grade UI components, native Tailwind CSS support, and advanced interactivity out of the box.

🚀 Key Features

  • ⚡ Pro Performance: without_count mode for lightning-fast paging on multi-million row tables.
  • 🎨 Premium UI Styles: Standard numbers, "Load More" buttons, and automated "Infinite Scroll".
  • 🌊 Native Tailwind Support: First-class support for Tailwind CSS utility classes.
  • ⌨️ Keyboard Navigation: Use Left/Right arrows to flip through pages.
  • 🔄 History API: AJAX updates automatically sync with the browser's URL and Back button.
  • 🌍 100% Localizable: Full I18n support for all labels, icons, and result strings.
  • 🛠 Advanced Helpers: Integrated page_entries_info and per_page_select components.
  • 🧩 Total Customization: Easy-to-use generator to export and modify HTML templates.

📦 Installation

Add this line to your application's Gemfile:

gem 'rails_pagination_ultimate', github: 'shiboshreeroy/rails_pagination_ultimate'

And then execute:

bundle install

📖 Usage

1. Basic Pagination

In your controller:

@posts = Post.page(params[:page]).per(25)

In your view:

<%= paginate @posts %>

2. Pro Navigation Modes

📱 Infinite Scroll (Modern Feed)

Automatically loads content as the user scrolls. Requires a target CSS selector.

<div id="posts-container">
  <%= render @posts %>
</div>

<%= paginate @posts, type: :infinite_scroll, target: "#posts-container" %>

🖱 "Load More" Button

A premium button that appends results without a full page reload.

<%= paginate @posts, type: :load_more, target: "#posts-container" %>

⌨️ Keyboard & History Support

Enable pro-level accessibility and shareable URLs for AJAX pagination:

<%= paginate @posts, theme: :tailwind, keyboard: true, history: true %>

⚡ Performance Optimization

Fast Mode (without_count)

Traditional pagination runs a COUNT(*) query which can be slow on large tables. RailsPaginationUltimate's "Fast Mode" skips this count entirely and uses an efficient look-ahead check for the next page.

# Controller
@posts = Post.without_count.page(params[:page]).per(50)

🎨 Customization & Theming

Use pro-grade Tailwind components by simply passing theme: :tailwind. No extra CSS files required!

<%= paginate @posts, theme: :tailwind, first_last: true, window: 3 %>

B. CSS Variables (Default Theme)

If you're not using Tailwind, the default theme is built with clean CSS variables for instant global styling:

:root {
  --rp-primary-color: #3b82f6; /* Your Brand Color */
  --rp-border-radius: 0.5rem;
  --rp-text-color: #1f2937;
  --rp-bg-color: #ffffff;
}

C. Total UI Control (Generator)

Need to change the HTML? Export the Pro Tailwind template to your app:

rails generate rails_pagination_ultimate:tailwind

This creates app/views/rails_pagination_ultimate/_pagination.html.erb. You can then use it like this:

<%= paginate @posts, template: "rails_pagination_ultimate/pagination" %>

🛠 Results Management

Detailed Information

Displays "Showing 1-25 of 150 results".

<%= page_entries_info @posts %>

Dynamic "Per Page" Selector

Let users choose how many items they want to see.

<%= per_page_select @posts, choices: [25, 50, 100], label: "Items per page:" %>

🌍 Localization (I18n)

Everything is translatable in config/locales/en.yml:

en:
  rails_pagination_ultimate:
    previous: "← Previous"
    next: "Next →"
    first: "« First"
    last: "Last »"
    info:
      other: "Showing <b>%{first}-%{last}</b> of <b>%{total}</b> results"
      without_count: "Showing <b>%{first}-%{last}</b> results"

📋 Options Reference

Option Type Default Description
theme Symbol nil Set to :tailwind for Tailwind UI.
type Symbol :standard :standard, :load_more, or :infinite_scroll.
target String nil CSS selector for where to append new items (AJAX).
window Integer 2 Number of page links around the current page.
first_last Boolean false Show "First" and "Last" page links.
keyboard Boolean false Enable Left/Right arrow key navigation.
history Boolean false Update browser URL/history on AJAX paging.
template String nil Path to a custom partial for rendering.

⚖️ Why switch from Kaminari?

Feature RailsPaginationUltimate Kaminari
Native Tailwind UI ✅ Built-in ❌ No
Infinite Scroll ✅ Built-in ❌ No
Fast Mode (No Count) ✅ Native ❌ Plugin required
Keyboard Shortcuts ✅ Built-in ❌ No
History API Sync ✅ Built-in ❌ No
Interactive Per-Page ✅ Built-in ❌ No
Modern Flexbox CSS ✅ Yes ❌ No

👨‍💻 Author & Credits

RailsPaginationUltimate is developed and maintained by Shiboshree Roy.

Built with ❤️ for the Rails community.

📄 License

The gem is available as open source under the terms of the MIT License.