@aniruddha1806/paginator

React Paginator

A powerful, customizable pagination component for React applications with TypeScript support. Features traditional pagination, infinite scroll, animations, and extensive customization options.

Installation

npm install @aniruddha1806/paginator

Features

• 📄 Traditional pagination with page numbers
• 🔄 Infinite scroll support with load more functionality
• 🎭 Animated transitions (slide, zoom effects)
• 🎯 Jump to page functionality
• 🎨 Extensive styling customization
• 📱 Responsive design with ellipsis for large page ranges
• 🔢 Item count and range display
• ♿ Accessibility features with ARIA support
• 🎛️ Customizable labels and buttons
• 📝 TypeScript support with full type definitions
• 🪶 Zero dependencies and lightweight

Quick Start

Basic Pagination

import Paginator from '@aniruddha1806/paginator';

function App() {
  const [currentPage, setCurrentPage] = useState(1);
  const totalPages = 10;

  return (
    <Paginator
      totalPages={totalPages}
      currentPage={currentPage}
      onPageChange={setCurrentPage}
    />
  );
}

Props

Core Props

Prop	Type	Default	Description
totalPages	number	required	Total number of pages
currentPage	number	required	Current active page (1-indexed)
onPageChange	(page: number) => void	required	Page change callback
maxVisiblePages	number	5	Maximum visible page buttons

Styling Props

Prop	Type	Default	Description
className	string	undefined	CSS class for container
buttonClassName	string	undefined	CSS class for page buttons
activeButtonClassName	string	undefined	CSS class for active button
disabledButtonClassName	string	undefined	CSS class for disabled buttons
prevNextButtonClassName	string	undefined	CSS class for prev/next buttons

Label Props

Prop	Type	Default	Description
prevLabel	React.ReactNode	"Previous"	Previous button label
nextLabel	React.ReactNode	"Next"	Next button label
firstLabel	React.ReactNode	"First"	First button label
lastLabel	React.ReactNode	"Last"	Last button label
showFirstLast	boolean	false	Show first/last buttons

Feature Props

Prop	Type	Default	Description
showJumpToPage	boolean	false	Show jump to page input
animateTransitions	boolean	false	Enable page transition animations
animationType	"slide" | "zoom"	"slide"	Animation type

Infinite Scroll Props

Prop	Type	Default	Description
infiniteScroll	boolean	false	Enable infinite scroll mode
onLoadMore	() => void	undefined	Load more callback
hasMoreItems	boolean	true	Whether more items are available
loadingLabel	React.ReactNode	"Loading more..."	Loading indicator text
itemsPerBatch	number	10	Items loaded per batch
totalItems	number	undefined	Total number of items

Examples

Basic Pagination

Simple pagination with default styling:

import { useState } from 'react';
import Paginator from '@aniruddha1806/paginator';

function BasicPaginationExample() {
  const [currentPage, setCurrentPage] = useState(1);
  const [data, setData] = useState([]);
  const itemsPerPage = 10;
  const totalItems = 100;
  const totalPages = Math.ceil(totalItems / itemsPerPage);

  // Simulate data loading
  const loadData = (page) => {
    const start = (page - 1) * itemsPerPage;
    const end = start + itemsPerPage;
    const newData = Array.from({ length: itemsPerPage }, (_, i) => ({
      id: start + i + 1,
      name: `Item ${start + i + 1}`
    }));
    setData(newData);
  };

  const handlePageChange = (page) => {
    setCurrentPage(page);
    loadData(page);
  };

  return (
    <div>
      <div style={{ minHeight: '400px', padding: '20px' }}>
        <h3>Items {((currentPage - 1) * itemsPerPage) + 1} - {Math.min(currentPage * itemsPerPage, totalItems)}</h3>
        <ul>
          {data.map(item => (
            <li key={item.id}>{item.name}</li>
          ))}
        </ul>
      </div>
      
      <Paginator
        totalPages={totalPages}
        currentPage={currentPage}
        onPageChange={handlePageChange}
      />
    </div>
  );
}

Advanced Pagination with All Features

Full-featured pagination with animations and jump functionality:

import { useState } from 'react';
import Paginator from '@aniruddha1806/paginator';

function AdvancedPaginationExample() {
  const [currentPage, setCurrentPage] = useState(1);
  const totalPages = 20;

  return (
    <div style={{ padding: '20px' }}>
      <h3>Advanced Pagination</h3>
      
      <Paginator
        totalPages={totalPages}
        currentPage={currentPage}
        onPageChange={setCurrentPage}
        maxVisiblePages={7}
        showFirstLast={true}
        showJumpToPage={true}
        animateTransitions={true}
        animationType="slide"
        prevLabel="← Prev"
        nextLabel="Next →"
        firstLabel="⇤ First"
        lastLabel="Last ⇥"
      />
      
      <div style={{ 
        marginTop: '20px', 
        padding: '16px', 
        backgroundColor: '#f8f9fa', 
        borderRadius: '8px' 
      }}>
        <p><strong>Current Page:</strong> {currentPage}</p>
        <p><strong>Total Pages:</strong> {totalPages}</p>
      </div>
    </div>
  );
}

Custom Styled Pagination

Apply custom styling with CSS classes:

import Paginator from '@aniruddha1806/paginator';
import './custom-pagination.css'; // Your custom CSS

function CustomStyledExample() {
  const [currentPage, setCurrentPage] = useState(1);

  return (
    <Paginator
      totalPages={15}
      currentPage={currentPage}
      onPageChange={setCurrentPage}
      className="custom-paginator"
      buttonClassName="custom-button"
      activeButtonClassName="custom-active"
      disabledButtonClassName="custom-disabled"
      prevNextButtonClassName="custom-nav-button"
    />
  );
}

CSS file (custom-pagination.css):

.custom-paginator {
  display: flex;
  justify-content: center;
  align-items: center;
  gap: 8px;
  padding: 20px;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  border-radius: 12px;
  box-shadow: 0 4px 15px rgba(0,0,0,0.1);
}

.custom-button {
  min-width: 40px;
  height: 40px;
  border-radius: 8px;
  border: 2px solid rgba(255,255,255,0.3);
  background: rgba(255,255,255,0.1);
  color: white;
  font-weight: 600;
  transition: all 0.3s ease;
}

.custom-button:hover {
  background: rgba(255,255,255,0.2);
  transform: translateY(-2px);
}

.custom-active {
  background: rgba(255,255,255,0.9);
  color: #667eea;
  border-color: rgba(255,255,255,0.9);
}

.custom-disabled {
  opacity: 0.4;
  cursor: not-allowed;
}

.custom-nav-button {
  padding: 0 16px;
  border-radius: 20px;
}

Infinite Scroll Example

Implement infinite scrolling for large datasets:

import { useState, useEffect } from 'react';
import Paginator from '@aniruddha1806/paginator';

function InfiniteScrollExample() {
  const [items, setItems] = useState([]);
  const [hasMore, setHasMore] = useState(true);
  const [loading, setLoading] = useState(false);

  // Simulate initial data load
  useEffect(() => {
    loadInitialData();
  }, []);

  const loadInitialData = () => {
    const initialItems = Array.from({ length: 20 }, (_, i) => ({
      id: i + 1,
      title: `Item ${i + 1}`,
      description: `Description for item ${i + 1}`
    }));
    setItems(initialItems);
  };

  const loadMore = async () => {
    if (loading) return;
    
    setLoading(true);
    
    // Simulate API call delay
    await new Promise(resolve => setTimeout(resolve, 1000));
    
    const currentLength = items.length;
    const newItems = Array.from({ length: 10 }, (_, i) => ({
      id: currentLength + i + 1,
      title: `Item ${currentLength + i + 1}`,
      description: `Description for item ${currentLength + i + 1}`
    }));
    
    setItems(prev => [...prev, ...newItems]);
    setLoading(false);
    
    // Stop loading more after 100 items
    if (items.length + newItems.length >= 100) {
      setHasMore(false);
    }
  };

  return (
    <div style={{ maxWidth: '600px', margin: '0 auto', padding: '20px' }}>
      <h2>Infinite Scroll Example</h2>
      
      <div style={{ marginBottom: '20px' }}>
        {items.map(item => (
          <div
            key={item.id}
            style={{
              padding: '16px',
              margin: '8px 0',
              border: '1px solid #e9ecef',
              borderRadius: '8px',
              backgroundColor: '#f8f9fa'
            }}
          >
            <h4 style={{ margin: '0 0 8px 0' }}>{item.title}</h4>
            <p style={{ margin: 0, color: '#666' }}>{item.description}</p>
          </div>
        ))}
      </div>
      
      <Paginator
        infiniteScroll={true}
        onLoadMore={loadMore}
        hasMoreItems={hasMore}
        loadingLabel={loading ? "Loading..." : "Load more items"}
        totalPages={0}
        currentPage={1}
        onPageChange={() => {}}
      />
      
      <div style={{ 
        textAlign: 'center', 
        marginTop: '20px', 
        color: '#666',
        fontSize: '14px'
      }}>
        Loaded {items.length} items
      </div>
    </div>
  );
}

TypeScript Usage

The component provides full TypeScript support:

import Paginator, { PaginatorProps } from '@aniruddha1806/paginator';
import { useState, useCallback } from 'react';

interface PaginatedData<T> {
  items: T[];
  totalPages: number;
  currentPage: number;
  totalItems: number;
}

interface User {
  id: number;
  name: string;
  email: string;
}

const PaginatedUserList: React.FC = () => {
  const [paginatedData, setPaginatedData] = useState<PaginatedData<User>>({
    items: [],
    totalPages: 0,
    currentPage: 1,
    totalItems: 0
  });

  const handlePageChange = useCallback((page: number): void => {
    // Fetch data for the new page
    fetchUsersForPage(page);
  }, []);

  const fetchUsersForPage = async (page: number): Promise<void> => {
    try {
      const response = await fetch(`/api/users?page=${page}`);
      const data = await response.json();
      setPaginatedData(data);
    } catch (error) {
      console.error('Error fetching users:', error);
    }
  };

  const paginatorProps: PaginatorProps = {
    totalPages: paginatedData.totalPages,
    currentPage: paginatedData.currentPage,
    onPageChange: handlePageChange,
    maxVisiblePages: 7,
    showJumpToPage: true,
    animateTransitions: true,
    totalItems: paginatedData.totalItems,
    itemsPerBatch: 10
  };

  return (
    <div>
      <div>
        {paginatedData.items.map(user => (
          <div key={user.id}>
            <h3>{user.name}</h3>
            <p>{user.email}</p>
          </div>
        ))}
      </div>
      <Paginator {...paginatorProps} />
    </div>
  );
};