Pagination

  • Use pagination to split long datasets like tables and lists
  • As a rule of thumb set pagination after 10, 15 or 20 items
  • Use small navigation on mobile and for small datasets

Normal

Page 1 of 10

Small

Page 1 of 10

API

Full example

export default () => {
const PAGE_SIZE = 20;
const TOTAL_ITEMS = 200;
const [currentPage, setCurrentPage] = useState(1);
const lastPage = Math.ceil(TOTAL_ITEMS / PAGE_SIZE);
return (
<Pagination
value={currentPage}
pageSize={PAGE_SIZE}
totalItems={TOTAL_ITEMS}
label={
<Text weak>
Page{' '}
<Text as="b" fontWeight="semibold" weak>
{currentPage} of {lastPage}
</Text>
</Text>
}
onNextPage={() => setCurrentPage(current => current + 1)}
onPrevPage={() => setCurrentPage(current => current - 1)}
onSkipForward={() => setCurrentPage(lastPage)}
onSkipBackward={() => setCurrentPage(1)}
/>
);
};

Label

The label should be used to display the current state of the pagination which typically consists of the current page and the total number of pages. This can be as simple as passing a string:

Page 1 of 20
<Pagination
value={currentPage}
pageSize={PAGE_SIZE}
totalItems={TOTAL_ITEMS}
label={`Page ${currentPage} of ${Math.ceil(TOTAL_ITEMS / PAGE_SIZE)}`}
/>

To display a label like in the examples above you can pass a custom component:

Page 1 of 20
<Pagination
value={currentPage}
pageSize={PAGE_SIZE}
totalItems={TOTAL_ITEMS}
label={
<Text weak>
Page{' '}
<Text as="b" fontWeight="semibold" weak>
{currentPage} of {lastPage}
</Text>
</Text>
}
/>

Accessibility

It is recommended to set ARIA labels to provide accessible names for the pagination inputs. This also helps when testing. You can use the following props to provide translated ARIA labels.

<Pagination
ariaLabelFirst="First"
ariaLabelPrevious="Previous"
ariaLabelNext="Next"
ariaLabelLast="Last"
/>

Testing

In tests you can use the aria-label attributes to select the individual buttons. Here is an example using @testing-library/react.

test('should select by aria-label', () => {
const { getByRole } = render(<Pagination value={1} pageSize={20} totalItems={200} />);
getByRole('button', { name: 'First' });
getByRole('button', { name: 'Previous' });
getByRole('button', { name: 'Next' });
getByRole('button', { name: 'Last' });
});