Nextjs-Pagination

Nextjs-Pagination is a powerful, customizable, and easy-to-use pagination component built specifically for Next.js projects. Designed with user experience in mind, it provides flexible configuration options so you can adjust the pagination behavior and look-and-feel to suit your needs. Nextjs-Pagination is built with TypeScript, offering type safety and autocompletion support in supported editors.

Features

• Customizable button color and shape: You can easily modify the color and shape of the pagination buttons. For instance, to make the buttons green and circular, you can pass color="green" and shape="circle" as props.
• Set maximum number of page buttons to display: You can limit the number of page buttons visible at a time. This is useful for large datasets where you don't want to display too many page buttons. For instance, to display up to 7 page buttons at a time, pass buttonCount={7} as a prop.
• Option to show or hide 'Next' and 'Prev' buttons: If you want to include 'Next' and 'Prev' buttons for easier navigation, you can do so by passing showNextPrev={true} as a prop.
• Option to show or hide 'First' and 'Last' buttons: Similarly, to include 'First' and 'Last' buttons for quick navigation to the first and last pages, pass showFirstLast={true} as a prop.
• Callback function for page changes: You can provide a function to be called whenever the page changes. This is useful for fetching new data based on the current page. Pass this function as the onPageChange prop.
• Customizable text for 'First', 'Prev', 'Next', 'Last' buttons: You can customize the text of the navigation buttons to suit your needs. They can accept any valid React node, such as text, emojis, symbols, etc. Here are some examples:
  • Text: For instance, firstText="Start", prevText="Backward", nextText="Forward", lastText="End"
  • Emojis: firstText="⏮", prevText="⏪", nextText="⏩", lastText="⏭"
  • Symbols: firstText="⇤", prevText="←", nextText="→", lastText="⇥"
  • Special Symbols: firstText="⟪", prevText="⟨", nextText="⟩", lastText="⟫"
• Customizable CSS classes for pagination container and buttons: You can add your own CSS classes to the pagination container and buttons for more advanced styling. For example, to add the CSS classes "pagination-container" and "pagination-button" to the pagination container and buttons respectively, pass className="pagination-container" and buttonClassName="pagination-button" as props. Remember to replace these with your own CSS classes.

Installation

Install the package using npm:

TypeScript

npm install nextjs-pagination

JavaScript

npm install nextjs-pagination

Usage

First, import the Pagination component from the nextjs-pagination package then use it in your components. Below are the 3 required props needed for JavaScript and TypeScript components:

TypeScript

import { Pagination } from 'nextjs-pagination';

const TSExample = () => {
  const handlePageChange = (page: number) => {
    setCurrentPage(page);
  };

  return (
    <Pagination
      onPageChange={handlePageChange}
      totalItems={100}
      itemsPerPage={10}
    />
  );
};

JavaScript

import Pagination from 'nextjs-pagination';

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

  return (
    <Pagination
      onPageChange={handlePageChange}
      totalItems={100}
      itemsPerPage={10}
    />
  );
};

This will render a pagination component for 100 items with 10 items per page.

API

Below are the props that you can pass to the Pagination component:

| Prop | Description | Type | Default | Required | |------------------|-------------------------------------------------------------------------------------------------------------------------|-----------------------|-----------|----------| | totalItems | Total number of items | number | - | Yes | | itemsPerPage | Number of items per page | number | - | Yes | | onPageChange | Callback function called when page changes | function | () => {} | Yes | | color | Button color | string | '#007bff' | No | | shape | Button shape ('circle' or 'square') | string | 'square' | No | | buttonCount | Maximum number of page buttons | number | 5 | No | | showNextPrev | Whether to show 'Next' and 'Prev' buttons | boolean | false | No | | showFirstLast | Whether to show 'First' and 'Last' buttons | boolean | false | No | | onSuccess | Callback function called when a valid page is selected | function | () => {} | No | | onError | Callback function called when an error occurs | function | () => {} | No | | customStyles | Custom styles for the buttons. You can use this to apply CSS-in-JS styles directly to the buttons. | React.CSSProperties | {} | No | | firstText | Text for the 'First' button. Can be any valid React node, such as text, emojis, symbols, etc. | React.ReactNode | 'First' | No | | prevText | Text for the 'Prev' button. Can be any valid React node, such as text, emojis, symbols, etc. | React.ReactNode | 'Prev' | No | | nextText | Text for the 'Next' button. Can be any valid React node, such as text, emojis, symbols, etc. | React.ReactNode | 'Next' | No | | lastText | Text for the 'Last' button. Can be any valid React node, such as text, emojis, symbols, etc. | React.ReactNode | 'Last' | No | | className | Custom CSS class name for the pagination container. You should replace this with your own CSS class name. | string | '' | No | | buttonClassName | Custom CSS class name for the buttons. You should replace this with your own CSS class name. | string | '' | No |

File Structure

• @types/
  • nextjs-pagination.d.ts - TypeScript declaration file for the package.
• dist/
  • index.js - Compiled JavaScript file of the package.
  • Pagination.js - Compiled JavaScript file of the package.
• src/
  • index.ts - Entry point file of the package.
  • Pagination.tsx - The main implementation of the pagination component.
• .babelrc - Babel configuration file.
• jest.config.js - Jest configuration file.
• package.json - Package metadata and dependency information.
• tsconfig.json - TypeScript configuration file.

Examples

Want to see it in action? CLICK HERE! to check our the example on replit.

(please give it a few seconds to start up the server when you load)

TypeScript Example

import { Pagination } from 'nextjs-pagination';

const ExamplePage: React.FC = () => {
  const handlePageChange = (page: number) => {
    setCurrentPage(page);
  };

  return (
    <Pagination
      totalItems={500}
      itemsPerPage={20}
      onPageChange={handlePageChange}
      color="green"
      shape="circle"
      buttonCount={7}
      showNextPrev={true}
      showFirstLast={true}
      onSuccess={(page: number) => console.log("Current page: ", page)}
      onError={(error: Error) => console.error(error)}
      firstText="First"
      lastText="Last"
      prevText="Prev"
      nextText="Next"
      className="custom-pagination-container-class"
      buttonClassName="custom-pagination-button-class"
    />
  );
};

JavaScript Example

import Pagination from 'nextjs-pagination';

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

  return (
    <Pagination
      totalItems={500}
      itemsPerPage={20}
      onPageChange={handlePageChange}
      color="green"
      shape="circle"
      buttonCount={7}
      showNextPrev={true}
      showFirstLast={true}
      onSuccess={(page) => console.log("Current page: ", page)}
      onError={(error) => console.error(error)}
      firstText="First"
      lastText="Last"
      prevText="Prev"
      nextText="Next"
      className="custom-pagination-container-class"
      buttonClassName="custom-pagination-button-class"
    />
  );
};

Contributing

We welcome contributions! Whether it's a bug report, feature request, or a code contribution, we greatly appreciate all help to improve Nextjs-Pagination. For major changes, please open an issue first to discuss what you would like to change.

License

Nextjs-Pagination is MIT licensed.