@sonardigital/pagination

Lightweight and customizable pagination component for React applications with built-in URL synchronization support.

Features

• 🎯 React Hook: Simple usePagination hook for state management
• 🔗 URL Sync: Optional URL parameter synchronization
• 🎨 Provider Pattern: Context-based state sharing across components
• ⚡ Navigation Controls: next, prev, jump, and reset functions
• 🛡️ Type Safety: Full TypeScript support
• 🔧 Flexible: Works with or without React Router

Installation

npm install @sonardigital/pagination

Peer Dependencies

This package requires the following peer dependencies:

{
  "react": "*",
  "react-dom": "*",
  "react-router": "*"
}

Quick Start

Basic Usage (Without URL Sync)

import { usePagination } from '@sonardigital/pagination';

function MyComponent() {
  const pagination = usePagination({
    page: 1,
    limit: 25,
    total: 100,
    onPageChange: ({ page, limit }) => {
      console.log(`Page: ${page}, Limit: ${limit}`);
      // Fetch data here
    }
  });

  return (
    <div>
      <button onClick={pagination.prev} disabled={pagination.disabledPrev}>
        Previous
      </button>
      <span>Page {pagination.page} of {pagination.totalPages}</span>
      <button onClick={pagination.next} disabled={pagination.disabledNext}>
        Next
      </button>
    </div>
  );
}

With URL Synchronization

import { usePagination } from '@sonardigital/pagination';

function MyComponent() {
  const pagination = usePagination({
    page: 1,
    limit: 25,
    total: 100,
    syncWithUrl: true,
    onPageChange: ({ page, limit }) => {
      // Fetch data when page/limit changes
      fetchData(page, limit);
    }
  });

  // URL will automatically update: ?page=2&limit=25
  return (
    <div>
      <button onClick={pagination.prev} disabled={pagination.disabledPrev}>
        Previous
      </button>
      <span>Page {pagination.page} of {pagination.totalPages}</span>
      <button onClick={pagination.next} disabled={pagination.disabledNext}>
        Next
      </button>
    </div>
  );
}

Using Provider Pattern

import { usePagination, PaginationProvider, usePaginationContext } from '@sonardigital/pagination';

function App() {
  const paginationMethods = usePagination({
    page: 1,
    limit: 25,
    total: 100,
    syncWithUrl: true
  });

  return (
    <PaginationProvider methods={paginationMethods}>
      <DataList />
      <PaginationControls />
    </PaginationProvider>
  );
}

function PaginationControls() {
  const pagination = usePaginationContext();

  return (
    <div>
      <button onClick={pagination.prev} disabled={pagination.disabledPrev}>
        Previous
      </button>
      <span>Page {pagination.page} of {pagination.totalPages}</span>
      <button onClick={pagination.next} disabled={pagination.disabledNext}>
        Next
      </button>
    </div>
  );
}

API Reference

usePagination(props)

Hook for managing pagination state.

Props

interface UsePaginationProps {
  page?: number;           // Initial page (default: 1)
  limit?: number;          // Items per page (default: 25)
  total?: number;          // Total number of items (default: 0)
  onPageChange?: (params: { page: number; limit: number }) => void;
  syncWithUrl?: boolean;   // Enable URL synchronization (default: false)
}

Returns

interface PaginationContextType {
  // State
  page: number;
  limit: number;
  totalItems: number;
  totalPages: number;
  
  // Navigation
  next: () => void;
  prev: () => void;
  jump: (pageNum: number) => void;
  reset: () => void;
  
  // Configuration
  setLimit: (limit: number) => void;
  setTotal: (total: number) => void;
  
  // Status
  disabledNext: boolean;
  disabledPrev: boolean;
  
  // Utilities
  queryParams: string;  // e.g., "page=1&limit=25"
}

PaginationProvider

Context provider for sharing pagination state across components.

interface PaginationProviderProps {
  methods: ReturnType<typeof usePagination>;
  children: React.ReactNode | React.ReactNode[];
}

usePaginationContext()

Hook to access pagination context within a PaginationProvider.

Advanced Examples

Changing Items Per Page

const pagination = usePagination({
  page: 1,
  limit: 25,
  total: 100
});

// Change limit (automatically resets to page 1)
pagination.setLimit(50);

Jumping to Specific Page

const pagination = usePagination({
  page: 1,
  limit: 25,
  total: 100
});

// Jump to page 5
pagination.jump(5);

Using Query Params

const pagination = usePagination({
  page: 1,
  limit: 25,
  total: 100
});

// Get formatted query string
const queryString = pagination.queryParams; // "page=1&limit=25"

// Use in API calls
fetch(`/api/items?${queryString}`);

Utilities

The package also exports utility functions for custom implementations:

paginationCalculations

import { paginationCalculations } from '@sonardigital/pagination';

paginationCalculations.calculateTotalPages(totalItems, limit);
paginationCalculations.isNextDisabled(currentPage, totalPages);
paginationCalculations.isPrevDisabled(currentPage);
paginationCalculations.isValidPage(pageNum, maxPages);

urlParams

import { urlParams } from '@sonardigital/pagination';

urlParams.parseUrlParam(value, defaultValue);
urlParams.getPaginationFromUrl(searchParams, defaultPage, defaultLimit);
urlParams.buildPaginationUrl(pathname, searchParams, page, limit);

Notes

• When syncWithUrl is enabled, pagination state syncs with URL query parameters
• Changing the limit automatically resets to page 1
• The hook handles browser back/forward navigation when URL sync is enabled
• Navigating to a new route resets pagination to initial values

License

ISC