Pagination

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 page
• itemsPerPageOptions - an array of numbers that are used to populate the items per page dropdown
• onItemsPerPageChange - a function that is called when the number of items per page is changed

() => {
	const [itemsPerPage, setItemsPerPage] = React.useState(25);

	return (
		<Pagination
			currentPage={1}
			totalPages={100 / itemsPerPage}
			generateHref={(page) => `/example?page=${page}`}
			itemsPerPage={itemsPerPage}
			itemsPerPageOptions={[10, 25, 50, 100]}
			onItemsPerPageChange={setItemsPerPage}
			itemRangeText={generatePaginationRangeText({
				totalItems: 100,
				currentPage: 1,
				itemsPerPage,
			})}
		/>
	);
};

Related patterns

• Search filters – Search filters help users find what they’re looking for by displaying options that meet specified criteria.