Pagination

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.

Sample

<cagov-pagination data-current-page="5" data-total-pages="99"></cagov-pagination>

Implementation notes

First, add the HTML.

<cagov-pagination data-current-page="5" data-total-pages="99"></cagov-pagination>

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.

const paginator = document.querySelector('cagov-pagination');

paginator.addEventListener('paginationClick', function (e) {
  alert(`You requested page ${e.detail}.`);
});

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

Usage

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

Behaviors

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.

Accessibility

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