react-router-pagination

React Router Pagination

A React Router 6 pagination component.

You have lots of data?
You want users to page through that data?
You want the page to be reflected in the route, and you're using React Router?

Given some simple props, React Router Pagination will create a list of links to those pages.

Example implementations are available on GitHub. You can also clone this repository and run Storybook.

Using the component

Required props:

A totalPages integer.

Not quite required but not quite optional props:

A pageNumber integer.

Optional props:

A match object, for generating the to prop of each <Link /> component.
An onClick handler, for when the user clicks a <Link />.

Additional props:

spread
format

Example

A component with props:

<Pagination
  totalPages={12}
  pageNumber={1}
/>

Generates:

<ul class="pagination">
    <li class="current-page">
        <a href="/1">
            <span class="page-number">1</span>
        </a>
    </li>
    <li class="page">
        <a href="/2">
            <span class="page-number">2</span>
        </a>
    </li>
    <li class="page">
       <a href="/3">
           <span class="page-number">3</span>
       </a>
    </li>
    <li class="page">
        <a href="/4">
            <span class="page-number">4</span>
        </a>
    </li>
    <li class="page">
        <a href="/5">
           <span class="page-number">5</span>
        </a>
    </li>
    <li class="forward-page">
        <a href="/6">
            <span class="forward">›</span>
        </a>
    </li>
    <li class="last-page">
        <a href="/12">
            <span class="page-number">12</span>
        </a>
    </li>
</ul>

(The default match object creates default route paths. You probably don't want that.)

About `totalPages`

React Router Pagination doesn't care about how many items you have and how many items you want to show per page.

It only cares about the total number of pages.

Your data contains 120 items which you want to display at 10 items per page.
Your data contains 60 items which you want to display at 5 items per page.
Your data contains 240 items which you want to display at 20 items per page.

In which case, totalPages should be 12.

<Pagination
  totalPages={12}
/>

Your data contains 121 items which you want to display at 10 items per page.
Your data contains 61 items which you want to display at 5 items per page.
Your data contains 241 items which you want to display at 20 items per page.

In which case, totalPages should be 13.

<Pagination
  totalPages={13}
/>

(Strings are coerced to numbers, and numbers are rounded.)

React Router Pagination only requires the total number of pages, which could be computed anywhere in your application ...

... But it does expose a static function for computing the totalPages:

const totalPages = Pagination.calculateTotalPages(120, 10)

Or:

const totalPages = Pagination.calculateTotalPages(121, 10)

(This is the same function the component uses internally.)

You can use this function anywhere in your application to ensure that the same value is being presented in different components.

About `pageNumber`

Your data contains 120 items which you want to display at 10 items per page.

To display page 1:

<Pagination
  totalPages={12}
  pageNumber={1}
/>

To display page 5:

<Pagination
  totalPages={12}
  pageNumber={5}
/>

(Strings are coerced to numbers, and numbers are rounded.)

React Router Pagination constrains pageNumber to a min of 1 and a max of totalPages.

Any of these will present page 1:

<Pagination
  totalPages={12}
  pageNumber={1}
/>

<Pagination
  totalPages={12}
/>

<Pagination
  totalPages={12}
  pageNumber={0}
/>

Either these will present page 12:

<Pagination
  totalPages={12}
  pageNumber={12}
/>

<Pagination
  totalPages={12}
  pageNumber={13}
/>

(Strings are coerced to numbers, and numbers are rounded.)

... React Router Pagination exposes a static function for computing the pageNumber prop:

const pageNumber = Pagination.calculatePageNumber(0, 12)

Or:

const pageNumber = Pagination.calculatePageNumber(13, 12)

Again, you can use this function anywhere in your application to ensure that the same value is being presented in different components.

Creating page routes with the `match` prop

The match prop has the same structure as React Router match prop.

The default has this structure:

{
  path: '/:pageNumber',
  params: {
    pageNumber: 1 /* or any integer */
  }
}

But your path is more complex. You have a <Route /> component matching the pattern:

/catalogue/products/:id

And you have a number of stores selling that product, for which you have a <Route /> component matching the pattern:

/catalogue/products/:id/stores/:pageNumber

Let's say the store id is ABCDEF.

For the list of stores, supply the Pagination component with a match prop of this structure:

{
  path: '/catalogue/products/:id/stores/:pageNumber',
  params: {
    id: 'ABCDEF'
  }
}

React Router Pagination uses the React Router utility generatePath to compute paths:

const getLinkTo = ({ path, params }, pageNumber) => generatePath(path, { ...params, pageNumber })

Given a totalPages of 12 and a spread of 5 then React Router Pagination will create a list of <Link /> components:

<ul class="pagination">
    <li class="current-page">
        <a href="/catalogue/products/ABCDEF/stores/1">
            <span class="page-number">1</span>
        </a>
    </li>
    <li class="page">
        <a href="/catalogue/products/ABCDEF/stores/2">
            <span class="page-number">2</span>
        </a>
    </li>
    <li class="page">
       <a href="/catalogue/products/ABCDEF/stores/3">
           <span class="page-number">3</span>
       </a>
    </li>
    <li class="page">
        <a href="/catalogue/products/ABCDEF/stores/4">
            <span class="page-number">4</span>
        </a>
    </li>
    <li class="page">
        <a href="/catalogue/products/ABCDEF/stores/5">
           <span class="page-number">5</span>
        </a>
    </li>
    <li class="forward-page">
        <a href="/catalogue/products/ABCDEF/stores/6">
            <span class="forward">›</span>
        </a>
    </li>
    <li class="last-page">
        <a href="/catalogue/products/ABCDEF/stores/12">
            <span class="page-number">12</span>
        </a>
    </li>
</ul>

What's spread?

Additional props, etc

spread
format

The value for spread should be an integer. It's the maximum number of page links to be displayed together.

Spread

If totalPages is 12, pageNumber is 1, and spread is 5, then links to pages 1, 2, 3, 4 and 5 will be displayed (as well as a "forward" link to page 6 and a link to the last page, 12).

Class names indicate the current-page, the forward-page, and the last-page.

<ul class="pagination">
    <li class="current-page">
        <a href="/1">
            <span class="page-number">1</span>
        </a>
    </li>
    <li class="page">
        <a href="/2">
            <span class="page-number">2</span>
        </a>
    </li>
    <li class="page">
        <a href="/3">
            <span class="page-number">3</span>
        </a>
    </li>
    <li class="page">
        <a href="/4">
            <span class="page-number">4</span>
        </a>
    </li>
    <li class="page">
        <a href="/5">
            <span class="page-number">5</span>
        </a>
    </li>
    <li class="forward-page">
        <a href="/6">
            <span class="forward">›</span>
        </a>
    </li>
    <li class="last-page">
        <a href="/12">
            <span class="page-number">12</span>
        </a>
    </li>
</ul>

If totalPages is 12, pageNumber is 4, and spread is 5, then links to pages 1, 2, 3, 4 and 5 will be displayed (as well as a "forward" link to page 6 and a link to the last page, 12).

Class names indicate the zero-page, the current-page, the forward-page, and the last-page.

<ul class="pagination">
    <li class="zero-page">
        <a href="/1">
            <span class="page-number">1</span>
        </a>
    </li>
    <li class="page">
        <a href="/2">
            <span class="page-number">2</span>
        </a>
    </li>
    <li class="page">
        <a href="/3">
            <span class="page-number">3</span>
        </a>
    </li>
    <li class="current-page">
        <a href="/4">
            <span class="page-number">4</span>
        </a>
    </li>
    <li class="page">
        <a href="/5">
            <span class="page-number">5</span>
        </a>
    </li>
    <li class="page">
        <a href="/6">
            <span class="page-number">6</span>
        </a>
    </li>
    <li class="forward-page">
        <a href="/7">
            <span class="forward">›</span>
        </a>
    </li>
    <li class="last-page">
        <a href="/12">
            <span class="page-number">12</span>
        </a>
    </li>
</ul>

If totalPages is 12, pageNumber is 8, and spread is 5, then links to pages 6, 7, 8, 9, and 10 will be displayed (as well as a "reverse" link to page 5, a "forward" link to page 11 and a link to the first page, 1, and the last page, 12).

Class names indicate the zero-page, the reverse-page, the current-page, the forward-page, and the last-page.

<ul class="pagination">
    <li class="zero-page">
        <a href="/1">
            <span class="page-number">1</span>
        </a>
    </li>
    <li class="reverse-page">
        <a href="/5">
            <span class="reverse">‹</span>
        </a>
    </li>
    <li class="page">
        <a href="/6">
            <span class="page-number">6</span>
        </a>
    </li>
    <li class="page">
        <a href="/7">
            <span class="page-number">7</span>
        </a>
    </li>
    <li class="current-page">
        <a href="/8">
            <span class="page-number">8</span>
        </a>
    </li>
    <li class="page">
        <a href="/9">
            <span class="page-number">9</span>
        </a>
    </li>
    <li class="page">
        <a href="/10">
            <span class="page-number">10</span>
        </a>
    </li>
    <li class="forward-page">
        <a href="/11">
            <span class="forward">›</span>
        </a>
    </li>
    <li class="last-page">
        <a href="/12">
            <span class="page-number">12</span>
        </a>
    </li>
</ul>

Format

Pass the format prop a value of "center" and a different calculation is used for the page links. You might prefer to try that one out than read about it. But it give it some good, solid numbers: lots of pages, with a spread of 5.

react-router-pagination

react-router-pagination