Pagination – Once UI

Pagination draws the controls for a list split into pages: previous and next buttons, the first and last pages, the pages around the current one, and an ellipsis for each run left out. It is a nav landmark named "Pagination" holding a list of buttons, and the current page carries aria-current="page".

Pagination

<Pagination total={12} defaultPage={5} />

Pass the number of pages as total, or the number of items as count with perPage, and Pagination works the page count out. An empty list is page 1 of 1.

Long ranges

The control keeps the same number of items wherever the current page is, so it does not change width as the reader pages through. boundaries sets how many pages are always drawn at each end, and siblings how many on each side of the current page. Both default to 1. An ellipsis never stands for a single page: that page is drawn instead.

Long ranges

<Pagination total={40} defaultPage={20} siblings={2} />
<Pagination total={40} defaultPage={20} boundaries={2} siblings={0} />

First and last

showFirstLast adds buttons that jump to either end, for very long ranges where the boundary pages are not enough.

First and last

<Pagination total={120} defaultPage={60} showFirstLast size="s" />

Controlled, with a page size

Pass page and onChange when the host owns the page, as it does when the page comes from the URL or a server request. perPageOptions adds a page-size select in front of the pages; pair perPage with onPerPageChange to own that too. When the size changes, the page moves so the first item on screen stays on screen, and onChange reports the move.

Controlled

Articles 1–20 of 248

const [page, setPage] = useState(1);
const [perPage, setPerPage] = useState(20);

<Pagination
page={page}
onChange={setPage}
count={248}
perPage={perPage}
perPageOptions={[10, 20, 50]}
onPerPageChange={setPerPage}
size="s"
/>

Accessibility

The landmark is named "Pagination". Give each one its own aria-label when a page has more than one, and to translate it. labels translates the arrow buttons and the per-page label.
Every control is a real button, reached with Tab. When an arrow reaches the first or last page and disables itself, focus moves to the current page instead of dropping to the document.
disabled turns every control off, such as while the next page loads.
Table draws its page buttons with Pagination when it is paginated.

API reference

	Type	Default
page The current page, from 1, when the host owns it. Pair with onChange.	number	—
defaultPage The page shown first when Pagination owns the state.	number	1
onChange Called with the new page; not for the page already shown.	(page: number) => void	—
total How many pages there are.	number	—
count How many items there are. With perPage, gives the page count.	number	—
perPage Items per page, when the host owns it.	number	—
defaultPerPage Items per page when Pagination owns it.	number	10
perPageOptions Page sizes to offer in a select. Without it there is no select.	number[]	—
onPerPageChange Called with the new page size.	(perPage: number) => void	—
siblings Pages drawn on each side of the current page.	number	1
boundaries Pages always drawn at each end.	number	1
showFirstLast Add first-page and last-page buttons.	boolean	false
size The buttons' size.	sml	m
disabled Disable every control.	boolean	false
labels The arrow buttons' names and the per-page label, to translate them.	Partial<PaginationLabels>	—
aria-label The landmark's name.	string	—
…and every FlexProps prop	inherited	—

PaginationLabels

	Type	Default
previous The previous-page button's name.	string	"Previous page"
next The next-page button's name.	string	"Next page"
first The first-page button's name.	string	"First page"
last The last-page button's name.	string	"Last page"
perPage The per-page select's label.	string	"Per page"