Bootstrap Usage

react-responsive-pagination is an easy to use React responsive pagination component which always outputs the right number of pagination elements for the width available, no guesswork needed

Ready to go with Bootstrap styles - see examples below

Not using Bootstrap? No problem, see the available ready-to-go themes including a standalone Bootstrap theme

Want to customise the appearance? See the Custom Styles guide

Installation

Install react-responsive-pagination from npm:

npm install react-responsive-pagination

To install Bootstrap styles, see the Bootstrap 5.x Download Guide

Bootstrap example

// Bootstrap 5.x or 4.x styles included somewhere in the project
import React, { useState } from 'react';
import ResponsivePagination from 'react-responsive-pagination';
import 'bootstrap/dist/css/bootstrap.css';


function MyBootstrapApp() {
  const totalPages = 120;


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


  function handlePageChange(page) {
    setCurrentPage(page);
    // ... do something with `page`
  }


  return (
    <ResponsivePagination
      total={totalPages}
      current={currentPage}
      onPageChange={page => handlePageChange(page)}
    />
  );
}

Options

Previous and Next Labels

Change the default labels for the previous and next buttons by setting the previousLabel and nextLabel props, see examples below

If needed, the ARIA labels can also be changed by setting the ariaPreviousLabel and ariaNextLabel props, please see Props Reference below

Example - Text labels

<ResponsivePagination ... previousLabel="Previous" nextLabel="Next" />

Example - Single arrow labels

<ResponsivePagination ... previousLabel="‹" nextLabel="›" />

No navigation buttons

Don't include the navigation buttons by setting renderNav to false:

Example - No navigation buttons

<ResponsivePagination ... renderNav={false} />

Alignment / Justify

Change how the pagination is positioned by setting the extraClassName prop to one of the Bootstrap justify content options. Here are some suitable values:

ValueAlignment
justify-content-startLeft
justify-content-endRight
justify-content-centerCenter (default)

Example - align pagination left:

<ResponsivePagination ... extraClassName="justify-content-start" />

Props Reference

A selection of props which may be helpful when using Bootstrap styles - for the full list of props see Props Reference

PropDescription
current
number
(required)

The current active page. Indexed from 1

total
number
(required)

The total number of pages

onPageChange
(newPage: number) => void
(required)

A callback handler which is called when the user clicks a new page. The newPage parameter is indexed from 1

Note that the active page will not change unless the current prop is updated to reflect the new page (as in the example above)

maxWidth
number
(optional)

The maximum width (in pixels) of the pagination component. Use this prop if you want to override the automatic sizing. Note the width may be exceeded if it's not possible a component to the specified width

previousLabel
string | ReactNode
(optional)

The label for the previous button, defaults to «

See the FAQ for further information on using React components for this prop

nextLabel
string | ReactNode
(optional)

The label for the next button, defaults to »

See the FAQ for further information on using React components for this prop

ariaPreviousLabel
string
(optional)

The accessibility ARIA label for the previous button, defaults to Previous

ariaNextLabel
string
(optional)

The accessibility ARIA label for the next button, defaults to Next

ariaCurrentAttr
boolean
(optional)

Set to false to prevent output of aria-current='page' for the active page <li>

See MDN's article on aria-current for further details

extraClassName
string
(optional)

Useful when using Bootstrap styles, extra classNames to be added to the top level <ul> container. Use this prop to override the default justify value - for example to align elements to the start of the page use: justify-content-start

Defaults to justify-content-center, not applicable if className prop is set

renderNav
boolean
(optional)

When set to false the nav buttons («/») will not be rendered. Defaults to true

narrowBehaviour
NarrowBehaviour
(optional)

Specify that nav buttons («/») and/or the ellipsis (…) can be dropped for very narrow widths (useful if the component is used in narrow widths with high page numbers)

Valid behaviours should be imported from react-responsive-pagination/narrowBehaviour, example:

import ResponsivePagination from 'react-responsive-pagination';
import { dropEllipsis } from 'react-responsive-pagination/narrowBehaviour';


<ResponsivePagination ... narrowBehaviour={dropEllipsis} />

Valid NarrowBehaviours:

dropEllipsis - drop the ellipsis (…) for narrow widths
dropNav - drop the nav («/») for narrow widths
dropFirstAndLast - drop the first and last pages for narrow widths

The default behaviour is to not drop any elements (this may change in a future major release)

Using Multiple NarrowBehaviours

Multiple NarrowBehaviours can be combined using the combine helper (also imported from react-responsive-pagination/narrowBehaviour), example:

import ResponsivePagination from 'react-responsive-pagination';
import { dropEllipsis, dropNav, combine } from 'react-responsive-pagination/narrowBehaviour';


<ResponsivePagination
  ...
  narrowBehaviour={combine(dropNav, dropEllipsis)}
/>

The behaviours will be applied in order so in this example, combine(dropNav, dropEllipsis) will drop the nav («/») initially and then further drop the ellipsis (…) if required