React Headless Pagination

Do you want to design your own pagination component, but do not want to worry about the logic of pagination? Then this tiny, performant and a11y proof package is for you. react-headless-pagination is ideal if you are working with a utility-based css framework like TailwindCSS. react-headless-pagination offers plenty of customization and is also fully typed.

Install

yarn add react-headless-pagination

Demo: Unstyled & TailwindCSS

Storybook

Usage

import { Pagination } from "react-headless-pagination";


...
const [page, setPage] = React.useState<number>(0);

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

return (
  <>
    Current page: {page + 1}
    <Pagination
      {...args}
      currentPage={page}
      setCurrentPage={handlePageChange}
      className=""
      truncableText="..."
      truncableClassName=""
    >
      <Pagination.PrevButton className="">Previous</Pagination.PrevButton>

      <nav className="flex justify-center flex-grow">
        <ul className="flex items-center">
          <Pagination.PageButton
            activeClassName=""
            inactiveClassName=""
            className=""
          />
        </ul>
      </nav>

      <Pagination.NextButton className="">Next</Pagination.NextButton>
    </Pagination>
  </>
);

An example of a styled version can be found in stories/PaginationTailwind.stories.tsx.

Pagination props

currentPage

Type: number

The value of current page. Required.

setCurrentPage

Type: (page: number) => void

Callback function once a page is updated. Can be directly used with a setState (see example above).

totalPages

Type: number

The number pages. Required.

edgePageCount

Type: number

The items size of one side of the edge of pagination. Default: 2

middlePagesSiblingCount

Type: number

The items size of one side of the middle of pagination. Default: 2

className

Type: string

Styles for the pagination container.

truncableText

Type: string

Text to render if a one or more pages are truncated.

truncableClassName

Type: string

Styles which can be applied to the TruncableElement.

Pagination.PrevButton props

children

Type: string | React.ReactNode

Content for the previous button.

className

Type: string

Styles for the previous button.

Pagination.NextButton props

children

Type: string | React.ReactNode

Content for the next button.

className

Type: string

Styles for the next button.

Pagination.PageButton props

as

Type: React.ReactElement Default:

Provide a custom React Element, such as a next/link component.

className

Type: string

dataTestIdActive

Type: string

data-testid in case the page button is active.

dataTestIdInactive

Type: string

data-testid in case the page button is active.

activeClassName

Type: string

Styles in case the page button is active.

inactiveClassName

Type: string

Styles in case the page button is inactive.

Authors

• Thijs Smudde

Taken inspiration from @makotot/paginated.

Contributing

PR's are always welcomed.

• Clone

To contribute to this project, start by cloning the repository to your local machine.

• Installation with Yarn

Before getting started, ensure that you have Yarn installed on your system. If not, you can install it by following the instructions on the official Yarn website.

• Run storybook: yarn storybook

To visualize and test components, run Storybook using the following command:

• Build tailwind: yarn watch:css

For styling, the project uses Tailwind CSS. To build Tailwind, run the following command: This command will watch for changes in your CSS files and rebuild Tailwind accordingly. Make sure to run this during development to keep styles up-to-date.