Provide simple pagination for search results or multi-page content.

Examples

Usage

Rules

  • Pagination is always centered on a page, and typically placed at the bottom of a page before the footer

Constraints

  • The pagination set can include up to 6 visible items (not including arrows), and ellipses will be used to represent a gap in successive visual page links

Principles

  • Pagination helps users navigation through a series of related pages

Accessibility

  • For pagination to be accessible it should be wrapped in a nav element and use aria-label. In this way the pagination can easily be navigated to with landmarks. See configuration table below.

Class Names

pagination
Required

Add to the <ul> that contains the page links
pagination-sm
Modifier

Use with .pagination for a visually smaller series of pagination links (used as the default choice to ensure that the strong of links fit on one line on smaller screens)
pagination-lg
Modifier

Use with .pagination for a visually larger series of pagination links. Only use when the number of results are limited to 3 or less, e.g. for an article that is broken out over several pages.
active
Required

Use with .page-item to indicate the currently selected page
page-item
Required

Use on the <li>s that contains the previous/next or page links
arrow
Modifier

Use with .page-item for the <li> that contains a previous or next link to increase the padding of the arrow link for more visibility
page-link
Required

Use on the page link <a>
page-gap
Modifier

Use on a <span> within a .page-item for the ellipses that visually represent a string of pages that gap the visible page links, e.g. 1 … 5, 6, 7

Configuration

aria-label
Required

Use on the <nav> element that is the parent of the .pagination list to identify it as pagination for assistive technology when viewing a list of landmarks, e.g. aria-label="Results Pagination"
aria-label
Required

Use on each .page-link within the pagination set to identify the page and its relationship to the set, e.g. aria-label="page 2 of 10, current page" for a current page or aria-label="page 2 of 10" for other pages in the set
aria-current="page"
Required

Use on the .page-link that represents the currently selected page
  • Last updated May 21, 2018
  • Not currently authorable
  • Core - Pagination