![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)
An accessible responsive React pagination component which intelligently renders to the available width - for React 16, 17 or 18
✅ Fully accessible with aria tags for screen readers
✅ Ready styled themes (or bring your own css)
✅ Bootstrap 4 & 5 support built-in
✅ Built for tree-shaking = minimum impact on the bundle
![react-responsive-pagination example](https://github.com/jonelantha/react-responsive-pagination/raw/HEAD/./react-responsive-pagination.gif?raw=true)
⭐️ What's new: August 2024 - SSR support
📕 Visit https://react-responsive-pagination.elantha.com to get started 🚀
v1 user? See the v1 migration guide to start using v2
⏳ Quick Start
npm install react-responsive-pagination
import React, { useState } from 'react';
import ResponsivePagination from 'react-responsive-pagination';
import 'react-responsive-pagination/themes/classic.css';
function MyApp() {
const [currentPage, setCurrentPage] = useState(8);
const totalPages = 20;
return (
<ResponsivePagination
current={currentPage}
total={totalPages}
onPageChange={setCurrentPage}
/>
);
}
Three ways to style:
-
🎨 Custom styling
Custom styles? No problem - see the Custom Styles Guide
-
🖼️ Ready-to-go themes (NEW!)
Just import one of the css themes into your project (as shown in the quickstart example above)
import 'react-responsive-pagination/themes/classic.css';
Please see the Themes guide for more details (including overridable theme attributes)
Want to create your own? See the Custom Styles Guide
-
🥾 Bootstrap 4 and 5
Using Bootstrap in your project? react-responsive-pagination just works with Bootstrap (no need for any additional styles). See the Bootstrap Getting Started Guide
✔︎ Requirements / Compatibility
- React 18, 17 and 16.8 upwards
- Modern browsers only - not suitable for IE 11
🔧 Props
Common Props
Prop | Description |
---|
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, note that the active page will not change unless the current prop is updated to reflect the new page (as in the example above). The newPage value is indexed from 1 |
maxWidth
number (optional) | The maximum width (in pixels) of the pagination component. Specify a value if you want to override the automatic sizing. Note this width may be exceeded in the case where it's not possible to output a small enough component |
ClassName Props
See Overriding default classNames for more information
Prop | Description |
---|
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 (above) 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 |
navClassName
string (optional) | Appended to <li> class name for nav items (« / » buttons):
<li class='page-item my-nav'><span class='page-link'>«</span></li> By defaults is not output |
previousClassName
string (optional) | Appended to <li> class name for the nav previous button (« ):
<li class='page-item my-previous-button'><span class='page-link'>«</span></li> By defaults is not output |
nextClassName
string (optional) | Appended to <li> class name for the nav next button (» ):
<li class='page-item my-next-button'><span class='page-link'>»</span></li> By defaults is not output |
Label Props
Prop | Description |
---|
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 |
Misc Props
Prop | Description |
---|
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 , see example
dropEllipsis - drop the ellipsis (…) for narrow widths
dropNav - drop the nav («/») for narrow widths
dropFirstAndLast - drop the first and last pages for narrow widths
Use the combine helper to combine narrowBehaviours, example:
narrowBehaviour={combine(dropNav, dropEllipsis)} - drop the nav initially and then further drop the ellipsis if required
combine should also be imported from react-responsive-pagination/narrowBehaviour see examples |
See Props Reference for the full list
ℹ About Auto Sizing
More info in the FAQ