Pagination is navigation for paginated content.
About the pagination component
When to use the pagination component
Search results. Pagination is most commonly used with paginated search results. Our Pagination component is designed to work both with results that have a discrete number of results pages (bounded) and those with an uncalculated number of results pages (unbounded). See Using the Pagination component, below, for more on bounded and unbounded sets.
Multi-page collections of related items. Splitting a large collection of related items into individual pages can improve browsability and scannability. Common examples of multi-page collections include articles related to a category or tag, content archives, and history or activity.
When to consider something else
Meaningful page groupings. If you have long content split meaningfully, or grouped by subject or theme, use conventional navigation like Side navigation.
Steps in a sequence. If you need to indicate progress in a series of steps that must be completed in succession, like an onboarding flow, consider using the step indicator component.
Short collections. If the length of the entire collection is less than 3-4 screen lengths long, consider showing all the items at once instead of paginating.
Show the size of the paginated set. Users want to know the length of a paginated section. This is most commonly accomplished by always showing the last page as the last item in the pagination navigation. Users should also know if the set is unbounded and has no discrete length. For example, some large search results will not have a “last” page. The USWDS Pagination component will always show the last page of the set as a navigable link, or show an ellipsis at the end of the links if the set is unbounded.
Highlight the current page. Pagination shows the current page the user is on in relation to the entire collection of pages.
Always include the first, previous, and next pages. Users should always be able to navigate to each of these pages from any page in the set.
Show navigation items in a single line. Pagination can be hard to understand — and individual items can be more difficult to select — when the items break over one line. Don’t split the navigation items over multiple lines. Avoid using Pagination in any context where it would be more than one line long.
- Indicate any missing pages. Don’t include out-of-sequence items directly adjacent to one another. Whenever there are pages missing — either between two elements, or at the end of an unbounded sequence — indicate the missing pages with an indicator like a non-selectable ellipsis.
- Use as few navigation items as possible. Showing more pages than necessary tends to add complexity and use more space without proportional increases to the component’s functionality. Focus on the essential actions and avoid adding more items to Pagination just to fill space.
- Use generous touch targets. Use touch targets that are big enough to select with any finger and have enough separation to avoid mistakes.
- Optimize the number of entries per page. Consider page load, performance, and the user’s scrolling preferences when determining how many items are displayed on each page. Some paginated content benefits from user control over the number of elements to show on each page.
<nav>element. Use a wrapping
<nav>element to identify Pagination as a navigation section to screen readers and other assistive technologies.
Use a unique, descriptive ARIA label for the <nav> element. Provide a descriptive ARIA label for any Pagination component’s
<nav>element that describes its purpose. For example, if the pagination component is used to navigate through a set of search results, an appropriate label could be
aria-label="search results page". If you use more than one Pagination component on a page, each will need a unique ARIA label.
Use an unordered list for the navigation items. This allows screen readers to voice the number of elements in the Pagination component
- Voice the current page. Use
aria-current="page"on the current page’s link item to properly voice the current page for screen readers.
- Voice the word “page” before the page numbers in links. Use
aria-label="page [#]"on each page link to be explicit that the numbers are links to page numbers.
- Voice “last page” on the last page’s link in a bounded set. Use
aria-label="last page, page [#]"to voice that the last element in the navigation is the last page in the paginated section. Don’t include this on the last navigation element in an unbounded set, since there is no last page in an unbounded set.
- Use a link for the current page for robustness. While it may sound counterintuitive to link to the current page in your Pagination component, it makes sense to include this as a link so screen readers voice the current page whether the user navigates by element or by tabbing.
- Avoid large horizontal gaps between elements. Users with limited vision or mobility may stop scanning and miss an element if there’s too much horizontal space between it and the previous element in the reading order.
Using the pagination component
- Set the current page item. Use the
usa-currentclass to highlight the currently active page.
- Pair with the Collection component. To display related items like articles or events in a compact list, consider using Pagination with the Collection component, which offers short descriptions and then directs users to the original source.
- Bounded and unbounded sets. The USWDS Pagination component is designed to work with both paginated sets that have a discrete number of pages (most paginated content) and those that do not. Bounded sets have a discrete number of pages and each page is potentially equally relevant (such as a set of blog posts sorted chronologically). Unbounded sets (often returned as a search result) are large sets sorted by relevance, where deeper pages have less relevance. Unbounded sets show no last page.
Pagination is navigation for paginated content. Taken as a whole, we call this paginated content a set. Each item in the set is a page and the page the reader is on is the current page.
The Pagination component includes seven equal-sized, equally spaced slots arranged in a single horizontal line. Each slot can accept a navigation item (typically a link to a specific page) or an overflow indicator (we use an ellipsis) to indicate that there are pages we're not showing. In the behaviors below, we'll number the slots 1–7, from left to right.
General component properties
- The component features a maximum of seven slots.
- Each slot can contain a navigation item or an overflow indicator.
- The first slot is always the first page of the set.
- If there are fewer than seven pages in the set, show only that number of slots.
- The component should always show the first page and current page.
- Show the next page, previous page, and last page if those pages exist.
- Display the same number of slots for each page in the set.
Remove extra slots if there are fewer than 7 pages.
Always highlight the current page.
Previouslink on the first page of the set and hide the
Nextlink on the last page of the set.
Always show both the previous page and the next page adjacent to the current page.
Show 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.
The background color of the entire pagination component, used for accessible color setting.
Breakpoint at which full pagination displays.
Default pagination button border radius.
Width of button border.
Default font family for pagination.
This component has no variants.
Meaningful code and guidance updates are listed in the following table:
Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656
Added support for high contrast mode and forced colors. All our components now support proper display when users have a forced colors mode set in their operating system. More information: uswds#4610
Added pagination component. Pagination is navigation for paginated content. More information: uswds#4175