Pagination
Pagination separates large amounts of content into separate pages, which helps reduce cognitive load.
import { ... } from '@ag.ds-next/react/pagination';
<Pagination currentPage={5} totalPages={10} generateHref={(page) => `/example?page=${page}`} />
Pagination allows users to see the total number of pages, which page they are viewing, and how to navigate to other pages.
Use pagination to separate large lists of content, such as search results, into smaller lists that are easier to interact with. Showing content on several pages prevents your content from becoming too long and overwhelming.
Do
- use to enable navigation to a large data set such as a long list of results
- use for table listings, search results, and directories
- indicate the current page
- use links over buttons where possible
- always place directly below the content you are paginating
- centre align with the content you are paginating.
Don’t
- display more than 5 page numbers between the ellipses dividers
- left or right align with the content you are paginating.
Pagination Buttons
By default, the Pagination
component renders a link for each list item. We strongly recommend using links wherever possible as it the most inclusive and accessible solution for users.
Links require you to manage the state of the current page in the URL, which usually is fine, but in scenarios where that isn’t possible, we offer a PaginationButtons
component.
PaginationButtons
renders a button element for each list item, which makes it possible to manage the state outside of the URL, e.g. React.useState
.
() => { const [currentPage, setCurrentPage] = React.useState(5); return ( <PaginationButtons currentPage={currentPage} onChange={setCurrentPage} totalPages={10} /> ); };
Range text
The Pagination
component accepts a itemRangeText
prop, which is used to display the range of items currently being displayed.
Use the generatePaginationRangeText
function to generate a string which follows the format of 1 - 10 of 458 items
.
<Pagination currentPage={5} totalPages={10} generateHref={(page) => `/example?page=${page}`} itemRangeText={generatePaginationRangeText({ totalItems: 100, currentPage: 5, itemsPerPage: 10, singularNoun: 'audit', // optional pluralNoun: 'audits', // optional })} />
Items per page
The Pagination
component accepts props which are used to display and change the number of items per page.
itemsPerPage
- the number of items per pageitemsPerPageOptions
- an array of numbers that are used to populate the items per page dropdownonItemsPerPageChange
- a function that is called when the number of items per page is changed
<Pagination currentPage={4} totalPages={4} generateHref={(page) => `/example?page=${page}`} itemsPerPage={25} itemsPerPageOptions={[10, 25, 50, 100]} onItemsPerPageChange={(itemsPerPage) => console.log(itemsPerPage)} itemRangeText={generatePaginationRangeText({ totalItems: 100, currentPage: 4, itemsPerPage: 25, })} />
Related patterns
- Search filters – Search filters help users find what they’re looking for by displaying options that meet specified criteria.