Custom Styles

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

Easy to completely customise, just add custom css to your project using this guide

  • 8

Don't want to create custom css? See the available ready-to-go themes

Using Bootstrap 5.x or 4.x? No problem, see the Bootstrap Pagination guide

Installation

Install react-responsive-pagination from npm:

npm install react-responsive-pagination

Quick Start

MyApp.js
import React, { useState } from 'react';
import ResponsivePagination from 'react-responsive-pagination';
import './pagination.css'; // see pagination.css example below
export default function MyApp() {
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)}
/>
);
}

See below for a pagination.css example

(for more information on Props, see Props Reference)

Custom Styling

To create custom styles for react-responsive-pagination simply include some custom css - the example below and the theme css source files should provide a good starting point. For a full list of suggested css selectors to target, see Selector Reference

Example

  • 8

For a full list of suggested css selectors to target, see Selector Reference

Further examples:
Please see the theme css files at: https://github.com/jonelantha/react-responsive-pagination/tree/main/packages/react-responsive-pagination/themes - these are also a good starting point for custom css files

Selector Reference

SelectorNotes
.paginationPagination container (<ul> tag)
The recommended style is a horizontal flexbox (see example above)
.page-itemItem containers (<li> tags)
Styles may not be needed for this selector, see selector below
.page-item .page-linkItem elements (<a> or <span> tags)
Includes links and static labels. Style as a block element with appropriate font, margin and border (see example above)
.page-item a.page-linkClickable item elements (<a> tags)
Page links or the next/previous buttons (if they are clickable)
.page-item.active .page-linkActive page link (<a> tags)
CSS should highlight this element (see example above)
.page-item.disabled .page-linkDisabled items (<span> tags)
Includes '...' or disabled nav buttons. CSS should show grey out these elements (see example above)

Overriding default classNames

If needed, you can easily override the default class names by adding the following props:

className PropDescription
classNameClass name for the top level <ul> container
pageItemClassNameClass name for all the <li> elements
pageLinkClassNameClass name for <a> or <span> child elements within an <li> element
activeItemClassNameAppended to <li> class name for the active element
disabledItemClassNameAppended to <li> class name for non-clickable elements (disabled nav buttons and the break/ellipsis)
navClassNameAppended to <li> class name for both nav buttons
previousClassNameAppended to <li> class name for previous nav button (overrides navClassName)
nextClassNameAppended to <li> class name for next nav button (overrides navClassName)

Example - overriding default class names

<ResponsivePagination
className="my-pagination"
pageItemClassName="my-item"
pageLinkClassName="my-link"
activeItemClassName="my-active"
disabledItemClassName="my-disabled"
navClassName="my-nav"
// ...other props
/>
// would create html like this
<ul class="my-pagination">
<li class="my-item my-disabled my-nav">
<span class="my-link" aria-label="Previous">
<span aria-hidden="true">«</span>
</span>
</li>
<li class="my-item my-active" aria-current="page">
<a class="my-link" href="#">1</a>
</li>
<li class="my-item">
<a class="my-link" href="#">2</a>
</li>
<!-- ... more elements -->
</ul>

Other Options

Previous and Next Labels

Change the default labels for the previous and next buttons by setting the previousLabel and nextLabel props:

Example - Text labels

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

Useful Props For Customisation

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

PropDescription
className
string
(optional)

Class name for the top level <ul> container

Defaults to pagination, overrides extraClassName prop (below)

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

pageItemClassName
string
(optional)

Class name for all the <li> elements

Defaults to page-item

pageLinkClassName
string
(optional)

Class name for <a> or <span> child elements within an <li> element:

<li ...><a class='page-link'>1</a></li>

Defaults to page-link

activeItemClassName
string
(optional)

Appended to <li> class name for the active element:

<li class='page-item active'><a class='page-link'>1</a></li>

Defaults to active

disabledItemClassName
string
(optional)

Appended to <li> class name for non-clickable elements (disabled nav buttons and the break/ellipsis):

<li class='page-item disabled'><span class='page-link'>...</span></li>

Defaults to disabled

string
(optional)

Appended to <li> class name for nav items (« / » buttons)

Setting to 'my-nav' would give html similar to:

<li class='page-item my-nav'><span class='page-link'>«</span></li>

By default will not be output

previousClassName
string
(optional)

Appended to <li> class name for the previous button («)

Setting to 'my-previous-button' would give html similar to:

<li class='page-item my-previous-button'><span class='page-link'>«</span></li>

Overrides navClassName and by default will not be output

nextClassName
string
(optional)

Appended to <li> class name for the next button (»)

Setting to 'my-next-button' would give html similar to:

<li class='page-item my-next-button'><span class='page-link'>»</span></li>

Overrides navClassName and by default will not be output

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

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