Cookies on ons.gov.uk

Cookies are small files stored on your device when you visit a website. We use some essential cookies to make this website work.

We would like to set additional cookies to remember your settings and understand how you use the site. This helps us to improve our services.

You have accepted all additional cookies. You have rejected all additional cookies. You can change your cookie preferences at any time.

Skip to main content

Pagination

Overview

Use the pagination component to help a user navigate a series of pages.

Example Pagination contents

Nunjucks

{% from "components/pagination/_macro.njk" import onsPagination %}

{{
    onsPagination({
        "currentPageNumber": 5,
        "pages": [
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            }
        ]
    })
}}

Nunjucks macro options

NameTypeRequiredDescription
pagesArray<Page>trueSettings for each page
currentPageNumberintegertrueSets the current page number
previousstringfalseText label for the “Previous” link. Default is “Previous”.
nextstringfalseText label for the “Next” link. Default is “Next”.
classesstringfalseClasses to add to the pagination HTML nav element
hideRangeIndicatorbooleanfalseSet to “true” to hide the range indicator on viewports ≥ 740px
headingLevelstringfalseNumber used to determine the heading level to ensure it has the correct semantic order on the page. Defaults to 2
Page
NameTypeRequiredDescription
urlstringtrueThe URL for the HTML href attribute for the page link

HTML

<nav class="ons-pagination " aria-label="Pagination (Page 5 of 35)">
  <div class="ons-pagination__position">Page 5 of 35</div>
  <ul class="ons-pagination__items">
    <li class="ons-pagination__item ons-pagination__item--previous">
      <a href="#0" class="ons-pagination__link ons-pagination__link--no-underline" rel="prev"
        aria-label="Go to the previous page (Page 4)"><svg class="ons-icon ons-icon--m ons-u-mr-xs" viewBox="0 0 17 13"
          xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor">
          <path
            d="M6.4.2.3 6.4c-.2.2-.2.4 0 .6l6.2 5.8c.2.2.4.1.6 0l.8-.9c.2-.2.1-.4 0-.6l-4-3.7h12.5c.2 0 .4-.2.4-.4V6c0-.2-.2-.4-.4-.4H3.8l4-4c.2-.1.2-.4.1-.5L7 .2c-.1-.1-.4-.1-.6 0z" />
        </svg><span class="ons-pagination__link-text">Previous</span>
      </a>
    </li>
    <li class="ons-pagination__item">
      <a href="#0" class="ons-pagination__link" aria-label="Go to the first page (Page 1)">1</a>
    </li>
    <li class="ons-pagination__item ons-pagination__item--gap">&hellip;</li>
    <li class="ons-pagination__item">
      <a href="#0" class="ons-pagination__link" aria-label="Go to page 4" rel="prev">4</a>
    </li>
    <li class="ons-pagination__item ons-pagination__item--current">
      <a href="#0" class="ons-pagination__link" aria-current="true" aria-label="Current page (Page 5 of 35)">5</a>
    </li>
    <li class="ons-pagination__item">
      <a href="#0" class="ons-pagination__link" aria-label="Go to page 6" rel="next">6</a>
    </li>
    <li class="ons-pagination__item ons-pagination__item--gap">&hellip;</li>
    <li class="ons-pagination__item">
      <a href="#0" class="ons-pagination__link" aria-label="Go to the last page (Page 35)">35</a>
    </li>
    <li class="ons-pagination__item ons-pagination__item--next">
      <a href="#0" class="ons-pagination__link ons-pagination__link--no-underline" rel="next"
        aria-label="Go to the next page (Page 6)">
        <span class="ons-pagination__link-text">Next</span><svg class="ons-icon ons-icon--m ons-u-ml-xs"
          viewBox="0 0 17 13" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor">
          <path
            d="m10 .2-.9.9c-.1.1-.1.4 0 .5l4 4H.6c-.2 0-.4.2-.4.4v1.2c0 .2.2.4.4.4h12.5l-3.9 3.7c-.2.2-.2.4 0 .6l.8.9c.2.2.4.2.6 0L16.8 7c.2-.2.2-.4 0-.6L10.7.3c-.3-.2-.5-.2-.7-.1z" />
        </svg></a>
    </li>
  </ul>
</nav>

When to use this component

This component will be most useful in contexts such as:

  • table listings of data
  • search results
  • directories

Showing the user a page at a time will prevent you from overwhelming them with too much information.

To find out how much information is 'too much' for a user, consider and test:

  • cognitive load
  • system load times
  • screen space

How to use this component

The pagination component should be left aligned after the content on each page that you are paginating.

For screens under the medium breakpoint, show the range indicator and hide the page numbers.

For larger screens, show page numbers for:

  • the current page
  • one page immediately before and after the current page (when applicable)
  • the first page and the last page

Use ellipses (...) to replace any skipped pages. For example:

  • [1] 2 … 10
  • 1 [2] 3 … 10
  • 1 2 [3] 4 … 10
  • 1 2 3 [4] 5 … 10
  • 1 ... 4 [5] 6 … 10
  • 1 … 5 [6] 7 ... 10
  • 1 … 6 [7] 8 9 10
  • 1 … 7 [8] 9 10
  • 1 … 8 [9] 10
  • 1 … 9 [10]

Variants

Long pagination (no range indicator)

Use this variant when there are up to ten pages of content.

The range indicator will be hidden on screens over the medium breakpoint. However, it will still show on smaller screens as the page numbers do not.

Example Pagination With No Range Indicator contents

Nunjucks
{% from "components/pagination/_macro.njk" import onsPagination %}

{{
    onsPagination({
        "hideRangeIndicator": true,
        "currentPageNumber": 5,
        "pages": [
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            }
        ]
    })
}}
Nunjucks macro options
NameTypeRequiredDescription
pagesArray<Page>trueSettings for each page
currentPageNumberintegertrueSets the current page number
previousstringfalseText label for the “Previous” link. Default is “Previous”.
nextstringfalseText label for the “Next” link. Default is “Next”.
classesstringfalseClasses to add to the pagination HTML nav element
hideRangeIndicatorbooleanfalseSet to “true” to hide the range indicator on viewports ≥ 740px
headingLevelstringfalseNumber used to determine the heading level to ensure it has the correct semantic order on the page. Defaults to 2
Page
NameTypeRequiredDescription
urlstringtrueThe URL for the HTML href attribute for the page link
HTML
<nav class="ons-pagination  ons-pagination--no-indicator" aria-label="Pagination (Page 5 of 10)">
  <div class="ons-pagination__position">Page 5 of 10</div>
  <ul class="ons-pagination__items">
    <li class="ons-pagination__item ons-pagination__item--previous">
      <a href="#0" class="ons-pagination__link ons-pagination__link--no-underline" rel="prev"
        aria-label="Go to the previous page (Page 4)"><svg class="ons-icon ons-icon--m ons-u-mr-xs" viewBox="0 0 17 13"
          xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor">
          <path
            d="M6.4.2.3 6.4c-.2.2-.2.4 0 .6l6.2 5.8c.2.2.4.1.6 0l.8-.9c.2-.2.1-.4 0-.6l-4-3.7h12.5c.2 0 .4-.2.4-.4V6c0-.2-.2-.4-.4-.4H3.8l4-4c.2-.1.2-.4.1-.5L7 .2c-.1-.1-.4-.1-.6 0z" />
        </svg><span class="ons-pagination__link-text">Previous</span>
      </a>
    </li>
    <li class="ons-pagination__item">
      <a href="#0" class="ons-pagination__link" aria-label="Go to the first page (Page 1)">1</a>
    </li>
    <li class="ons-pagination__item ons-pagination__item--gap">&hellip;</li>
    <li class="ons-pagination__item">
      <a href="#0" class="ons-pagination__link" aria-label="Go to page 4" rel="prev">4</a>
    </li>
    <li class="ons-pagination__item ons-pagination__item--current">
      <a href="#0" class="ons-pagination__link" aria-current="true" aria-label="Current page (Page 5 of 10)">5</a>
    </li>
    <li class="ons-pagination__item">
      <a href="#0" class="ons-pagination__link" aria-label="Go to page 6" rel="next">6</a>
    </li>
    <li class="ons-pagination__item ons-pagination__item--gap">&hellip;</li>
    <li class="ons-pagination__item">
      <a href="#0" class="ons-pagination__link" aria-label="Go to the last page (Page 10)">10</a>
    </li>
    <li class="ons-pagination__item ons-pagination__item--next">
      <a href="#0" class="ons-pagination__link ons-pagination__link--no-underline" rel="next"
        aria-label="Go to the next page (Page 6)">
        <span class="ons-pagination__link-text">Next</span><svg class="ons-icon ons-icon--m ons-u-ml-xs"
          viewBox="0 0 17 13" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor">
          <path
            d="m10 .2-.9.9c-.1.1-.1.4 0 .5l4 4H.6c-.2 0-.4.2-.4.4v1.2c0 .2.2.4.4.4h12.5l-3.9 3.7c-.2.2-.2.4 0 .6l.8.9c.2.2.4.2.6 0L16.8 7c.2-.2.2-.4 0-.6L10.7.3c-.3-.2-.5-.2-.7-.1z" />
        </svg></a>
    </li>
  </ul>
</nav>

Pager

Use the pager variant to allow users to switch between a small number of pages of content.

This variant can be used within short guides or multi-paged HTML documents where the next and previous page is known to the user.

Example Content Pagination contents

Nunjucks
{% from "components/content-pagination/_macro.njk" import onsContentPagination %}

{{-
  onsContentPagination({
    "contentPaginationItems": [
      {
        "rel": 'prev',
        "text": 'Previous',
        "url": '#0',
        "label": 'Overview'
      },
      {
        "rel": 'next',
        "text": 'Next',
        "url": '#0',
        "label": 'Who should take part and why'
      }
    ]
  })
}}
Nunjucks macro options
NameTypeRequiredDescription
ariaLabelstringfalseThe ARIA label added to the HTML nav landmark. Required when multiple navigation landmarks are on a page. Defaults to “Guide pagination”.
contentPaginationItemsArray<contentPaginationItem>trueSettings for the pagination items
contentPaginationItem
NameTypeRequiredDescription
urlstringtrueThe URL for the pagination link
relstringtrueSets the HTML rel attribute on the link to set the correct arrow icon. Set to “next” or “prev”.
textstringtrueText for the pagination link
bridgingTextstringfalseSets the visually hidden text for screen readers to bridge the text and label. Defaults to “page in this guide is:”. For example, “Next page in this guide is: ‘Who should take part and why’.
labelstringtrueTitle of the next or previous page
HTML
<nav class="ons-content-pagination" aria-label="Guide pagination">
  <ul class="ons-content-pagination__list">
    <li class="ons-content-pagination__item">
      <a href="#0" class="ons-content-pagination__link" rel="prev">
        <span class="ons-content-pagination__link-title">
          <svg class="ons-icon ons-icon--m" viewBox="0 0 17 13" xmlns="http://www.w3.org/2000/svg" focusable="false"
            fill="currentColor">
            <path
              d="M6.4.2.3 6.4c-.2.2-.2.4 0 .6l6.2 5.8c.2.2.4.1.6 0l.8-.9c.2-.2.1-.4 0-.6l-4-3.7h12.5c.2 0 .4-.2.4-.4V6c0-.2-.2-.4-.4-.4H3.8l4-4c.2-.1.2-.4.1-.5L7 .2c-.1-.1-.4-.1-.6 0z" />
          </svg><span class="ons-content-pagination__link-text">Previous</span>
        </span>
        <span class="ons-content-pagination__link-divider ons-u-vh">page in this guide is:</span>
        <span class="ons-content-pagination__link-label">Overview</span>
      </a>
    </li>
    <li class="ons-content-pagination__item">
      <a href="#0" class="ons-content-pagination__link" rel="next">
        <span class="ons-content-pagination__link-title">
          <svg class="ons-icon ons-icon--m" viewBox="0 0 17 13" xmlns="http://www.w3.org/2000/svg" focusable="false"
            fill="currentColor">
            <path
              d="m10 .2-.9.9c-.1.1-.1.4 0 .5l4 4H.6c-.2 0-.4.2-.4.4v1.2c0 .2.2.4.4.4h12.5l-3.9 3.7c-.2.2-.2.4 0 .6l.8.9c.2.2.4.2.6 0L16.8 7c.2-.2.2-.4 0-.6L10.7.3c-.3-.2-.5-.2-.7-.1z" />
          </svg><span class="ons-content-pagination__link-text">Next</span>
        </span>
        <span class="ons-content-pagination__link-divider ons-u-vh">page in this guide is:</span>
        <span class="ons-content-pagination__link-label">Who should take part and why</span>
      </a>
    </li>
  </ul>
</nav>

Help improve this page

Let us know how we could improve this page, or share your user research findings. Discuss the ‘Pagination’ component on GitHub (opens in a new tab)