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
| Name | Type | Required | Description |
|---|---|---|---|
| pages | Array<Page> | true | Settings for each page |
| currentPageNumber | integer | true | Sets the current page number |
| previous | string | false | Text label for the “Previous” link. Default is "Previous". |
| next | string | false | Text label for the “Next” link. Default is "Next". |
| classes | string | false | Classes to add to the pagination HTML nav element |
| hideRangeIndicator | boolean | false | Set to “true” to hide the range indicator on viewports ≥ 740px |
| Name | Type | Required | Description |
|---|---|---|---|
| url | string | true | The 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-2xs" viewBox="0 0 17 13"
xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img"
title="ons-icon-arrow-previous">
<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">…</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">…</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-2xs"
viewBox="0 0 17 13" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img"
title="ons-icon-arrow-next">
<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
| Name | Type | Required | Description |
|---|---|---|---|
| pages | Array<Page> | true | Settings for each page |
| currentPageNumber | integer | true | Sets the current page number |
| previous | string | false | Text label for the “Previous” link. Default is "Previous". |
| next | string | false | Text label for the “Next” link. Default is "Next". |
| classes | string | false | Classes to add to the pagination HTML nav element |
| hideRangeIndicator | boolean | false | Set to “true” to hide the range indicator on viewports ≥ 740px |
| Name | Type | Required | Description |
|---|---|---|---|
| url | string | true | The 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-2xs" viewBox="0 0 17 13"
xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img"
title="ons-icon-arrow-previous">
<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">…</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">…</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-2xs"
viewBox="0 0 17 13" xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img"
title="ons-icon-arrow-next">
<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
| Name | Type | Required | Description |
|---|---|---|---|
| ariaLabel | string | false | The ARIA label added to the HTML nav landmark. Required when multiple navigation landmarks are on a page. Defaults to “Guide pagination”. |
| contentPaginationItems | Array<contentPaginationItem> | true | Settings for the pagination items |
| Name | Type | Required | Description |
|---|---|---|---|
| url | string | true | The URL for the pagination link |
| rel | string | true | Sets the HTML rel attribute on the link to set the correct arrow icon. Set to “next” or “prev”. |
| text | string | true | Text for the pagination link |
| bridgingText | string | false | Sets 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’. |
| label | string | true | Title 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" role="img"
title="ons-icon-arrow-previous">
<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" role="img" title="ons-icon-arrow-next">
<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)