react-pagination-ultra

A customizable React pagination component built with TypeScript, designed to provide a flexible and reusable solution for paginating content in your React applications. This component supports dynamic page number generation, navigation buttons (first, previous, next, last), and extensive styling customization through className props.

Features

Dynamic Page Numbers: Automatically displays a configurable number of page buttons centered around the current page.
Navigation Controls: Includes buttons for navigating to the first page, previous page, next page, and last page.
Customizable Styling: Override default styles using className, arrowsClassName, and pageNumbersClassName props.
TypeScript Support: Fully typed with TypeScript for a better developer experience.
Lightweight and Performant: Built with performance in mind, with minimal dependencies.

Demo

Watch a quick demo of the PaginationPro component in action:

Sorry, your browser doesn't support embedded videos, but you can download it to watch.

Installation

Install react-pagination-ultra using npm and yarn:

npm install react-pagination-ultra

yarn add react-pagination-ultra

Usage

Import the Pagination component and its default styles, then use it in your React application. Below is a basic example:

import React, { useState } from 'react';
import PaginationPro from 'react-pagination-ultra';
import 'react-pagination-ultra/dist/style.css'; // Import default styles

const App: React.FC = () => {
  const [currentPage, setCurrentPage] = useState(1); // Start at page 1
  const totalPages = 10; // Total number of pages

  const handlePageChange = (page: number) => {
    setCurrentPage(page);
    console.log(`Navigated to page ${page}`);
  };

  return (
    <div style={{ padding: '20px', textAlign: 'center' }}>
      <h1>React Pagination Ultra Example</h1>
      <PaginationPro
        currentPage={currentPage}
        totalPages={totalPages}
        onPageChange={handlePageChange}
        dispayNoOfItems={false} // Hide the item range display
        maxPagesToShow={5}
      />
    </div>
  );
};

export default App;

Props

The Pagination component accepts the following props:

Prop Name	Type	Default Value	Description
`currentPage`	`number`	-	The current active page number (required).
`totalPages`	`number`	-	The total number of pages (required).
`onPageChange`	`(page: number) => void`	-	Callback function invoked when a page is selected (required).
`className`	`string`	`''`	Custom class name for the parent container to override default styles.
`pageRangeClassName`	`string`	`''`	Custom class name for the parent container to override default styles.
`styleContainer`	`object`	`''`	Style prop for the parent container to change default styles.
`arrowsClassName`	`string`	`''`	Custom class name for the arrow buttons (first, previous, next, last).
`pageNumbersClassName`	`string`	`''`	Custom class name for the page number buttons.
`maxPagesToShow`	`number`	`5`	The maximum number of page buttons to display at a time (optional).
`itemsPerPage`	`number`	`10`	Number of items per page, used to calculate the item range display.
`totalItems`	`number`	`0`	The total number of items across all pages (required if show `dispayNoOfItems`).
`dispayNoOfItems`	`boolean`	`true`	Show or hide the item range display (e.g., "Showing 1 to 10 of 100 items")

Prop Details

currentPage: Specifies the currently active page. The component highlights this page and uses it to determine which page numbers to display.
totalPages: Defines the total number of pages available. This determines the range of pages the user can navigate to.
onPageChange: A callback function that is called whenever the user navigates to a new page (e.g., by clicking a page number or an arrow button). The function receives the new page number as an argument.
className: Allows you to apply custom styles to the entire pagination container. Use this to change the background, padding, border, etc.
pageRangeClassName: Allows you to apply custom styles to the displayNoOfItem Page Range. Use this to change the style.
styleContainer: Allows you to apply custom styles to the entire pagination container. Use this to change the background, padding, border, etc.
arrowsClassName: Applies custom styles to the navigation arrow buttons (first, previous, next, last). Useful for changing the appearance of these buttons.
pageNumbersClassName: Applies custom styles to the page number buttons. You can use this to change the appearance of the page numbers, including the active page (which has the active class).
maxPagesToShow: Controls how many page numbers are displayed at a time. For example, if set to 5, the component will show up to 5 page numbers centered around the current page (e.g., if currentPage is 5, it might show pages 3, 4, 5, 6, 7).
itemsPerPage: Specifies the number of items to display per page. Used to calculate the item range displayed on the current page (e.g., "Showing 1 to 10 of 100 items"). It defaults to 10.
totalItems: Specifies the total number of items across all pages. Used to calculate the item range displayed on the current page (e.g., "Showing 1 to 10 of 100 items").
dispayNoOfItems: Specifies whether to show the item range display (e.g., "Showing 1 to 10 of 100 items"). If set to false, the item range will be hidden. It defaults to true..

Default Styles

The component comes with default styles that match a clean, modern design:

White background with a subtle shadow for the container.
Rounded buttons with a light gray border.
Blue highlight for the active page with white text.
Disabled buttons (e.g., when on the first or last page) are faded out.

You can override these styles using the className, arrowsClassName, and pageNumbersClassName props, as shown in the "Custom Styling" section.

Custom Styling

To customize the look and feel of the pagination component, you can use the className, arrowsClassName, and pageNumbersClassName props.

For example:

<PaginationPro
  currentPage={currentPage}
  totalPages={totalPages}
  onPageChange={handlePageChange}
  dispayNoOfItems={false} // Hide the item range display
  className="custom-pagination"
  arrowsClassName="custom-arrows"
  pageNumbersClassName="custom-page-numbers"
  maxPagesToShow={5}
/>

Then, define your custom styles in your CSS file:

/* custom-pagination.css */

.custom-pagination {
  background-color: #f0f0f0;
  border-radius: 8px;
  padding: 10px;
}

.custom-arrows {
  background-color: #007bff;
  color: white;
}

.custom-arrows:hover {
  background-color: #0056b3;
}

.custom-page-numbers {
  color: #007bff;
  border: 1px solid #007bff;
  padding: 5px 10px;
}

.custom-page-numbers.active {
  background-color: #007bff;
  color: white;
}

To use this CSS file in your project, import it like this:

import './custom-pagination.css';

License

This project is licensed under the ISC License.