Pagination

Quick start guide and documentation

2-Minute Setup

1 Include CSS File

Required Files • HTML

2 Add Pagination HTML

Basic Pagination • HTML
✓ Done! Your pagination is ready with hover states, active page styling, and accessibility built-in.

Quick Reference

Classes

Class Element Purpose
.rsl-pagination <ul> Main pagination container
.active <li> Current page indicator
.disabled <li> Disabled prev/next buttons
.compact <ul> Smaller size variant

ARIA Attributes

Attribute Where Purpose
aria-label Prev/Next/First/Last links Descriptive label for screen readers
aria-current="page" Active page link Indicates current page
aria-disabled="true" Disabled links Indicates disabled state
role="navigation" Wrapper (optional) Identifies as navigation landmark

HTML Structure Patterns

Standard Pagination

Complete Example • HTML

With Icons

Icon Pagination • HTML

With First/Last Buttons

First/Last Buttons • HTML

Disabled State (First Page)

Disabled Previous • HTML

Ellipsis for Long Ranges

With Ellipsis • HTML

Configuration Options

Compact Size

Smaller pagination for tight spaces or mobile views.

Compact CSS • CSS

.rsl-pagination.compact a {
    padding: 6px 10px;
    font-size: 0.875rem;
}

Disabled State Styling

Disabled State • CSS

.rsl-pagination .disabled a {
    opacity: 0.5;
    cursor: not-allowed;
    pointer-events: none;
}

JavaScript Behavior

Automatic Table Pagination

The included pagination.js provides automatic table pagination with zero configuration. Simply include the script and add the proper classes:

How it works:
  • Automatically finds all tables with .rsl-table class
  • Pairs them with nearby .rsl-pagination controls
  • Shows 10 rows per page by default
  • Updates active states and disabled states automatically
  • Handles Previous, Next, First, Last, and numbered page links
Setup Example • HTML




    
        

            ID
            Name
            Email
        

    
    
        
1Alicealice@example.com

        
2Bobbob@example.com

Key Features

Custom Implementation

For custom pagination behavior (e.g., AJAX loading, different page sizes), implement your own click handlers:

Custom Handler • JavaScript

// Custom pagination handler
document.querySelectorAll('.rsl-pagination a').forEach(link => {
    link.addEventListener('click', function(e) {
        e.preventDefault();

        // Remove active class from all items
        document.querySelectorAll('.rsl-pagination li').forEach(li => {
            li.classList.remove('active');
        });

        // Add active class to clicked item
        this.parentElement.classList.add('active');

        // Your custom logic here
        loadPageContent(this.textContent);
    });
});

Accessibility

Required ARIA Attributes

Best Practice: Always include descriptive aria-label attributes on prev/next/first/last links, and use aria-current="page" on the active page.
Accessible Example • HTML

Keyboard Navigation

Focus Management

Tip: When pagination changes content, move focus to the newly loaded content or back to a heading to help screen reader users understand the page change.
Focus Management • JavaScript

// After loading new page content
function loadPage(pageNum) {
    // Load content...

    // Move focus to content area
    const contentHeading = document.querySelector('#content h2');
    if (contentHeading) {
        contentHeading.setAttribute('tabindex', '-1');
        contentHeading.focus();
    }
}

Color Contrast

WCAG Requirement: Ensure pagination links have sufficient color contrast (minimum 4.5:1 for normal text, 3:1 for large text). Test with tools like WebAIM's Contrast Checker.

Integration with RSL

Pagination works seamlessly with all RSL components:

With RSL Grid • HTML




    
Card 1

    
Card 2

    
Card 3

JSON Layout API Integration

The Pagination component is fully compatible with RSL's JSON Layout API, enabling declarative table pagination through JavaScript configuration. Components automatically initialize after rendering via RSL.JSONLayout.renderLayout().

✅ Automatic Initialization: When you render a layout containing .rsl-table and .rsl-pagination elements using the JSON API, the pagination automatically initializes without manual setup.
Basic JSON API Example • JavaScript

// Create table HTML with pagination
const tableHTML = `
  <table class="rsl-table">
    <thead>
      <tr>
        <th>ID</th>
        <th>Name</th>
        <th>Email</th>
      </tr>
    </thead>
    <tbody>
      <tr><td>1</td><td>User 1</td><td>user1@example.com</td></tr>
      <!-- Add more rows... -->
    </tbody>
  </table>

  <ul class="rsl-pagination">
    <li><a href="#">Previous</a></li>
    <li><a href="#">1</a></li>
    <li><a href="#">2</a></li>
    <li><a href="#">3</a></li>
    <li><a href="#">Next</a></li>
  </ul>
`;

// Render via JSON API - pagination auto-initializes!
const config = {
  version: 1,
  layoutId: "paginated-table",
  breakpoints: { xs: 1 },
  items: [{
    id: "table-item",
    content: { type: "html", value: tableHTML }
  }]
};

RSL.JSONLayout.renderLayout('#container', config);
// Pagination is now active - no manual init() needed!
📚 Want More Examples? Check out the Pagination JSON API Examples page for:
  • Basic pagination with 25 rows
  • Large datasets with First/Last controls
  • Multiple independent paginated tables on one page

Public API Methods

Method Description
RSL.Pagination.init() Scan and initialize all paginated tables (auto-called by JSON API)
RSL.Pagination.create(table, pagination, rowsPerPage) Manually create pagination for specific table
RSL.Pagination.showPage(table, pageNum) Programmatically navigate to a specific page
RSL.Pagination.instances Map of initialized table instances
RSL.Pagination.destroy(table) Destroy pagination instance and cleanup FilterBus subscriptions

FilterBus Integration

Pagination can subscribe to RSL's FilterBus to automatically reset to page 1 when filters change. This is ideal for dashboard scenarios where filter buttons affect table content - when the data changes, users should start at page 1.

How It Works:
  • Add data-filter-subscribe="key1,key2" to the pagination element
  • When any subscribed filter key changes, pagination resets to page 1
  • Works with region filters, date pickers, search boxes, or any FilterBus publisher
  • Emits rsl-pagination:filterbus-reset event when reset occurs

FilterBus Attributes

Attribute Type Description
data-filter-subscribe String Comma-separated list of FilterBus keys to subscribe to (e.g., "region", "region,dateFilter")

Example

FilterBus Pagination • HTML

Subscribe to Multiple Filters

Multiple Filter Keys • HTML

Events

Event Detail Description
rsl-pagination:filterbus-reset { state, meta, previousPage } Fired when pagination resets to page 1 due to a FilterBus update
⚠️ Important: This Pagination component works with the Tables component (.rsl-table), not Smart Table. The Smart Table component has its own built-in pagination that integrates with its filtering and sorting features. Use this Pagination component when you have a table using the Tables component with external filter controls.
📺 See It In Action: Check out the FilterBus Dashboard Demo to see pagination auto-resetting when filters change, alongside Smart Table, KPI Cards, Charts, and more!

Pro Tips

✨ Tip 1: Use ellipsis (...) for page ranges with more than 7-10 pages to keep the UI clean
✨ Tip 2: Always disable prev button on first page and next button on last page
✨ Tip 3: Consider using icons (fa-chevron-left/right) instead of text for a cleaner look
✨ Tip 4: For mobile, show fewer page numbers (first, current, last + ellipsis)
✨ Tip 5: Add "Showing X-Y of Z results" text above pagination for clarity
✨ Tip 6: Use query parameters (?page=2) for bookmarkable and shareable pagination

Troubleshooting

Pagination Not Centered?

Active State Not Showing?

Disabled Links Still Clickable?

Pagination Not Working on Mobile?

Next Steps

See Examples

View pagination.html for realistic use cases

Copy Templates

Use playground.html as a starting point

Explore More

Browse all RSL Components and examples