Pagination splits information over multiple pages. It helps your audience navigate between pages for information.

The controls allow you to move forward or backward or go directly to a specific page.


First, add the HTML.

This component accepts data attributes for the number of pages and current page. These changes are monitored and the component re-renders if these attributes change:

Name Attribute name Data type Field type
Current page data-current-page string Integer (default is 1)
Total pages data-total-pages string Integer (default is 1, enter -1 for an unbound set)

It also accepts optional strings for all the text so it can be used in multiple languages:

Name Attribute name Data type Field type
Previous data-previous string Plain text (default is " Previous")
Next data-next string Plain text (default is "Next ")

Next, register an event to respond to clicks.

Replace the alert with your own code to retrieve the content for the requested page and write it into the DOM.


When and how to use it

Use pagination when:

  • Showing all the content on a single page is too much and causes poor performance
  • Most users will only need the content on the first few pages
  • A long list of content could benefit from pagination

The default number displayed will vary depending on the context.

Add the pagination component after the content on each page that you’re paginating. Use pagination if it improves the performance or usability of your service.

Common uses of pagination include:

  • Search results
  • A list of announcements or press releases
  • A glossary

How not to use it

Do not use pagination:

  • To break up long pages of text
  • When the content works better as a bulleted list
  • For a list of steps


This describes the different pagination behaviors. The maximum number of slots (page numbers and ellipsis) displayed are 7. There are a few instances when not all 7 slots are displayed.

Do not show pagination if there’s only one page of content. For example, you get 3 search results on 1 page, do not show pagination.

Guideline Live example
Remove extra slots if there are less than 7 pages.
Always highlight the current page.
Hide the Previous link on the first page of the set and hide the Next link on the last page of the set.
Always show both the previous page and the next page adjacent to the current page.
Use ellipsis as an overflow indicator when there are pages missing.
Bounded sets can show overflow indicators in Slot 2 and Slot 6 only.
Unbounded sets always show an overflow indicator in Slot 7.
Unbounded sets use Slot 4 as the current page for pages 4 and higher.


Component-specific accessibility review

  • Make sure that each pagination link has appropriate aria-label.
  • Make sure that pagination component is contained within nav tag and has aria-label="Pagination” added to it.

Standard accessibility review

Each time a new component version is published:

  • Test with the axe accessibility tool
  • Review with the VoiceOver or NVDA screen reader
  • Ensure all actionable elements are accessible by keyboard command and tab in a logical order
  • Check the component layout on a variety of screen sizes