Pagination
Pagination is used to navigate a series of pages in a linear or semi-linear manner, allowing you to display a portion of information and avoid overwhelming the user with too much information.
Variants
Long pagination
<nav class="pagination " arial-label="Pagination (Page 5 of 35)">
<div class="pagination__position">Page 5 of 35</div>
<ul class="pagination__items">
<li class="pagination__item pagination__item--previous">
<a href="#" class="pagination__link" rel="prev" aria-label="Go to the previous page (Page 4)">Previous</a>
</li>
<li class="pagination__item">
<a href="#" class="pagination__link" aria-label="Go to the first page (Page 1)">1</a>
</li>
<li class="pagination__item pageination__item--gap">…</li>
<li class="pagination__item">
<a href="#" class="pagination__link" aria-label="Go to page 3">3</a>
</li>
<li class="pagination__item">
<a href="#" class="pagination__link" aria-label="Go to page 4" rel="prev">4</a>
</li>
<li class="pagination__item pagination__item--current">
<a href="#" class="pagination__link" aria-current="true" aria-label="Current page (Page 5 of 35)">5</a>
</li>
<li class="pagination__item">
<a href="#" class="pagination__link" aria-label="Go to page 6" rel="next">6</a>
</li>
<li class="pagination__item">
<a href="#" class="pagination__link" aria-label="Go to page 7">7</a>
</li>
<li class="pagination__item pageination__item--gap">…</li>
<li class="pagination__item">
<a href="#" class="pagination__link" aria-label="Go to the last page (Page 35)">35</a>
</li>
<li class="pagination__item pagination__item--next">
<a href="#" class="pagination__link" rel="next" aria-label="Go to the next page (Page 6)">Next</a>
</li>
</ul>
</nav>
{% from "components/pagination/_macro.njk" import onsPagination %}
{{
onsPagination({
"previous": "Previous",
"next": "Next",
"pages": [
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#",
"current": true
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
},
{
"url": "#"
}
]
})
}}
{% macro onsPagination(params) %}
{% set currentPageIndex = "" %}
{% for page in params.pages %}
{% if page.current is defined and page.current %}
{% set currentPageIndex = loop.index %}
{% endif %}
{% endfor %}
{% set totalPages = params.pages | length %}
{% set position = "Page " + currentPageIndex + " of " + totalPages %}
{# Calculate middle pages #}
{% set middlePageCount = 5 %}
{% set middlePagesEachSide = (middlePageCount - 1) / 2 %}
{% if (currentPageIndex - middlePagesEachSide) <= 1 %}
{% set middlePagesStart = 1 %}
{% set middlePagesEnd = middlePageCount - 1 %}
{% elif (currentPageIndex + middlePagesEachSide) >= totalPages %}
{% set middlePagesStart = totalPages - middlePageCount + 1 %}
{% set middlePagesEnd = totalPages %}
{% else %}
{% set middlePagesStart = currentPageIndex - middlePagesEachSide %}
{% set middlePagesEnd = currentPageIndex + middlePagesEachSide %}
{% endif %}
<nav class="pagination {{ params.classes }}{% if params.hideRangeIndicator is defined and params.hideRangeIndicator %} pagination--no-indicator{% endif %}" arial-label="Pagination ({{ position }})">
<div class="pagination__position">{{ position }}</div>
<ul class="pagination__items">
{% if currentPageIndex != 1 %}
{% set prevPageIndex = currentPageIndex - 2 %}
<li class="pagination__item pagination__item--previous">
<a href="{{ params.pages[prevPageIndex].url }}" class="pagination__link" rel="prev" aria-label="Go to the previous page (Page {{ currentPageIndex - 1 }})">{{ params.previous }}</a>
</li>
{% endif %}
{% if currentPageIndex > 3 %}
{% set first = params.pages | first %}
<li class="pagination__item">
<a href="{{ first.url }}" class="pagination__link" aria-label="Go to the first page (Page 1)">1</a>
</li>
{% endif %}
{% if currentPageIndex > 4 %}
<li class="pagination__item pageination__item--gap">…</li>
{% endif %}
{% for page in params.pages %}
{% if loop.index >= middlePagesStart and loop.index <= middlePagesEnd %}
<li class="pagination__item{% if page.current is defined and page.current == true %} pagination__item--current{% endif %}">
<a href="{{ page.url }}" class="pagination__link"
{%- if page.current -%}
aria-current="true" aria-label="Current page ({{ position }})"
{%- else -%}
aria-label="Go to page {{ loop.index }}"
{%- endif -%}
{%- if loop.index == currentPageIndex - 1 -%}
rel="prev"
{%- endif -%}
{%- if loop.index == currentPageIndex + 1 -%}
rel="next"
{%- endif -%}
>{{ loop.index }}</a>
</li>
{% endif %}
{% endfor %}
{% if currentPageIndex < totalPages - 3 %}
<li class="pagination__item pageination__item--gap">…</li>
{% endif %}
{% if currentPageIndex < totalPages - 2 %}
{% set lastPage = params.pages | last %}
<li class="pagination__item">
<a href="{{ lastPage.url }}" class="pagination__link" aria-label="Go to the last page (Page {{ totalPages }})">{{ totalPages }}</a>
</li>
{% endif %}
{% if totalPages > 1 and totalPages != currentPageIndex %}
<li class="pagination__item pagination__item--next">
<a href="{{ params.pages[currentPageIndex].url }}" class="pagination__link" rel="next" aria-label="Go to the next page (Page {{ currentPageIndex + 1 }})">{{ params.next }}</a>
</li>
{% endif %}
</ul>
</nav>
{% endmacro %}
$pagination-item-padding: 0.5rem;
$pagination-item-width: 2.5rem;
.pagination {
$ctx: &;
&__items {
margin: 0 $pagination-item-padding * -1;
padding: 0;
}
&__item {
display: none;
text-align: center;
&--previous,
&--next {
display: inline-block;
}
@include mq(m) {
&:not(&--previous) {
display: inline-block;
}
}
}
&__item,
&__link {
height: $pagination-item-width;
min-width: $pagination-item-width;
}
&__link {
border-radius: 3px;
display: block;
padding: $pagination-item-padding;
&:hover,
&:focus {
background: $color-grey-5;
}
}
&__item--current &__link {
background: $color-text-link-hover;
color: $color-white;
text-decoration: none;
}
&--no-indicator & {
&__position {
@include mq(m) {
display: none;
}
}
}
}
Long pagination (no range indicator)
The range indicator will be hidden on desktop, however it will still show on mobile as the page numbers don’t show.
<nav class="pagination pagination--no-indicator" arial-label="Pagination (Page 7 of 35)">
<div class="pagination__position">Page 7 of 35</div>
<ul class="pagination__items">
<li class="pagination__item pagination__item--previous">
<a href="#page6" class="pagination__link" rel="prev" aria-label="Go to the previous page (Page 6)">Previous</a>
</li>
<li class="pagination__item">
<a href="#page1" class="pagination__link" aria-label="Go to the first page (Page 1)">1</a>
</li>
<li class="pagination__item pageination__item--gap">…</li>
<li class="pagination__item">
<a href="#page5" class="pagination__link" aria-label="Go to page 5">5</a>
</li>
<li class="pagination__item">
<a href="#page6" class="pagination__link" aria-label="Go to page 6" rel="prev">6</a>
</li>
<li class="pagination__item pagination__item--current">
<a href="#page7" class="pagination__link" aria-current="true" aria-label="Current page (Page 7 of 35)">7</a>
</li>
<li class="pagination__item">
<a href="#page8" class="pagination__link" aria-label="Go to page 8" rel="next">8</a>
</li>
<li class="pagination__item">
<a href="#page9" class="pagination__link" aria-label="Go to page 9">9</a>
</li>
<li class="pagination__item pageination__item--gap">…</li>
<li class="pagination__item">
<a href="#page35" class="pagination__link" aria-label="Go to the last page (Page 35)">35</a>
</li>
<li class="pagination__item pagination__item--next">
<a href="#page8" class="pagination__link" rel="next" aria-label="Go to the next page (Page 8)">Next</a>
</li>
</ul>
</nav>
{% from "components/pagination/_macro.njk" import onsPagination %}
{{
onsPagination({
"previous": "Previous",
"next": "Next",
"hideRangeIndicator": true,
"pages": [
{
"url": "#page1"
},
{
"url": "#page2"
},
{
"url": "#page3"
},
{
"url": "#page4"
},
{
"url": "#page5"
},
{
"url": "#page6"
},
{
"url": "#page7",
"current": true
},
{
"url": "#page8"
},
{
"url": "#page9"
},
{
"url": "#page10"
},
{
"url": "#page11"
},
{
"url": "#page12"
},
{
"url": "#page13"
},
{
"url": "#page14"
},
{
"url": "#page15"
},
{
"url": "#page16"
},
{
"url": "#page17"
},
{
"url": "#page18"
},
{
"url": "#page19"
},
{
"url": "#page20"
},
{
"url": "#page21"
},
{
"url": "#page22"
},
{
"url": "#page23"
},
{
"url": "#page24"
},
{
"url": "#page25"
},
{
"url": "#page26"
},
{
"url": "#page27"
},
{
"url": "#page28"
},
{
"url": "#page29"
},
{
"url": "#page30"
},
{
"url": "#page31"
},
{
"url": "#page32"
},
{
"url": "#page33"
},
{
"url": "#page34"
},
{
"url": "#page35"
}
]
})
}}
{% macro onsPagination(params) %}
{% set currentPageIndex = "" %}
{% for page in params.pages %}
{% if page.current is defined and page.current %}
{% set currentPageIndex = loop.index %}
{% endif %}
{% endfor %}
{% set totalPages = params.pages | length %}
{% set position = "Page " + currentPageIndex + " of " + totalPages %}
{# Calculate middle pages #}
{% set middlePageCount = 5 %}
{% set middlePagesEachSide = (middlePageCount - 1) / 2 %}
{% if (currentPageIndex - middlePagesEachSide) <= 1 %}
{% set middlePagesStart = 1 %}
{% set middlePagesEnd = middlePageCount - 1 %}
{% elif (currentPageIndex + middlePagesEachSide) >= totalPages %}
{% set middlePagesStart = totalPages - middlePageCount + 1 %}
{% set middlePagesEnd = totalPages %}
{% else %}
{% set middlePagesStart = currentPageIndex - middlePagesEachSide %}
{% set middlePagesEnd = currentPageIndex + middlePagesEachSide %}
{% endif %}
<nav class="pagination {{ params.classes }}{% if params.hideRangeIndicator is defined and params.hideRangeIndicator %} pagination--no-indicator{% endif %}" arial-label="Pagination ({{ position }})">
<div class="pagination__position">{{ position }}</div>
<ul class="pagination__items">
{% if currentPageIndex != 1 %}
{% set prevPageIndex = currentPageIndex - 2 %}
<li class="pagination__item pagination__item--previous">
<a href="{{ params.pages[prevPageIndex].url }}" class="pagination__link" rel="prev" aria-label="Go to the previous page (Page {{ currentPageIndex - 1 }})">{{ params.previous }}</a>
</li>
{% endif %}
{% if currentPageIndex > 3 %}
{% set first = params.pages | first %}
<li class="pagination__item">
<a href="{{ first.url }}" class="pagination__link" aria-label="Go to the first page (Page 1)">1</a>
</li>
{% endif %}
{% if currentPageIndex > 4 %}
<li class="pagination__item pageination__item--gap">…</li>
{% endif %}
{% for page in params.pages %}
{% if loop.index >= middlePagesStart and loop.index <= middlePagesEnd %}
<li class="pagination__item{% if page.current is defined and page.current == true %} pagination__item--current{% endif %}">
<a href="{{ page.url }}" class="pagination__link"
{%- if page.current -%}
aria-current="true" aria-label="Current page ({{ position }})"
{%- else -%}
aria-label="Go to page {{ loop.index }}"
{%- endif -%}
{%- if loop.index == currentPageIndex - 1 -%}
rel="prev"
{%- endif -%}
{%- if loop.index == currentPageIndex + 1 -%}
rel="next"
{%- endif -%}
>{{ loop.index }}</a>
</li>
{% endif %}
{% endfor %}
{% if currentPageIndex < totalPages - 3 %}
<li class="pagination__item pageination__item--gap">…</li>
{% endif %}
{% if currentPageIndex < totalPages - 2 %}
{% set lastPage = params.pages | last %}
<li class="pagination__item">
<a href="{{ lastPage.url }}" class="pagination__link" aria-label="Go to the last page (Page {{ totalPages }})">{{ totalPages }}</a>
</li>
{% endif %}
{% if totalPages > 1 and totalPages != currentPageIndex %}
<li class="pagination__item pagination__item--next">
<a href="{{ params.pages[currentPageIndex].url }}" class="pagination__link" rel="next" aria-label="Go to the next page (Page {{ currentPageIndex + 1 }})">{{ params.next }}</a>
</li>
{% endif %}
</ul>
</nav>
{% endmacro %}
$pagination-item-padding: 0.5rem;
$pagination-item-width: 2.5rem;
.pagination {
$ctx: &;
&__items {
margin: 0 $pagination-item-padding * -1;
padding: 0;
}
&__item {
display: none;
text-align: center;
&--previous,
&--next {
display: inline-block;
}
@include mq(m) {
&:not(&--previous) {
display: inline-block;
}
}
}
&__item,
&__link {
height: $pagination-item-width;
min-width: $pagination-item-width;
}
&__link {
border-radius: 3px;
display: block;
padding: $pagination-item-padding;
&:hover,
&:focus {
background: $color-grey-5;
}
}
&__item--current &__link {
background: $color-text-link-hover;
color: $color-white;
text-decoration: none;
}
&--no-indicator & {
&__position {
@include mq(m) {
display: none;
}
}
}
}
Pager
<nav class="content-pagination" aria-label="Guide pagination">
<ul class="content-pagination__list">
<li class="content-pagination__item">
<a href="#" class="content-pagination__link" rel="prev">
<span class="content-pagination__link-title">
<svg class="content-pagination__link-icon" xmlns="http://www.w3.org/2000/svg" height="13" width="17" viewBox="0 0 17 13">
<path d="M6.4,0.2L0.3,6.4c-0.2,0.2-0.2,0.4,0,0.6l6.2,5.8c0.2,0.2,0.4,0.1,0.6,0l0.8-0.9c0.2-0.2,0.1-0.4,0-0.6L3.9,7.6h12.5c0.2,0,0.4-0.2,0.4-0.4V6c0-0.2-0.2-0.4-0.4-0.4H3.8l4-4C8,1.5,8,1.2,7.9,1.1L7,0.2C6.9,0.1,6.6,0.1,6.4,0.2z" fill="currentColor"></path>
</svg>
<span class="content-pagination__link-text">
Previous
</span>
</span>
<span class="content-pagination__link-divider u-vh">page in this guide is:</span>
<span class="content-pagination__link-label">Overview</span>
</a>
</li>
<li class="content-pagination__item">
<a href="#" class="content-pagination__link" rel="next">
<span class="content-pagination__link-title">
<svg class="content-pagination__link-icon" xmlns="http://www.w3.org/2000/svg" height="13" width="17" viewBox="0 0 17 13">
<path d="M10,0.2L9.1,1.1C9,1.2,9,1.5,9.1,1.6l4,4H0.6C0.4,5.6,0.2,5.8,0.2,6v1.2c0,0.2,0.2,0.4,0.4,0.4h12.5l-3.9,3.7c-0.2,0.2-0.2,0.4,0,0.6l0.8,0.9c0.2,0.2,0.4,0.2,0.6,0l6.2-5.8c0.2-0.2,0.2-0.4,0-0.6l-6.1-6.1C10.4,0.1,10.2,0.1,10,0.2z" fill="currentColor"></path>
</svg>
<span class="content-pagination__link-text">
Next
</span>
</span>
<span class="content-pagination__link-divider u-vh">page in this guide is:</span>
<span class="content-pagination__link-label">Who should take part and why</span>
</a>
</li>
</ul>
</nav>
{% from "components/content-pagination/_macro.njk" import onsContentPagination %}
{{-
onsContentPagination({
"contentPaginationItems": [
{
"rel": 'prev',
"text": 'Previous',
"url": '#',
"label": 'Overview'
},
{
"rel": 'next',
"text": 'Next',
"url": '#',
"label": 'Who should take part and why'
}
]
})
}}
{% macro onsContentPagination(params) %}
<nav class="content-pagination" aria-label="{{ params.ariaLabel | default("Guide pagination") }}">
<ul class="content-pagination__list">
{% for contentPaginationItem in params.contentPaginationItems %}
<li class="content-pagination__item">
<a href="{{ contentPaginationItem.url }}" class="content-pagination__link" rel="{{ contentPaginationItem.rel }}">
<span class="content-pagination__link-title">
<svg class="content-pagination__link-icon" xmlns="http://www.w3.org/2000/svg" height="13" width="17" viewBox="0 0 17 13">
{% if contentPaginationItem.rel === 'prev' %}
<path d="M6.4,0.2L0.3,6.4c-0.2,0.2-0.2,0.4,0,0.6l6.2,5.8c0.2,0.2,0.4,0.1,0.6,0l0.8-0.9c0.2-0.2,0.1-0.4,0-0.6L3.9,7.6h12.5c0.2,0,0.4-0.2,0.4-0.4V6c0-0.2-0.2-0.4-0.4-0.4H3.8l4-4C8,1.5,8,1.2,7.9,1.1L7,0.2C6.9,0.1,6.6,0.1,6.4,0.2z" fill="currentColor"></path>
{% else %}
<path d="M10,0.2L9.1,1.1C9,1.2,9,1.5,9.1,1.6l4,4H0.6C0.4,5.6,0.2,5.8,0.2,6v1.2c0,0.2,0.2,0.4,0.4,0.4h12.5l-3.9,3.7c-0.2,0.2-0.2,0.4,0,0.6l0.8,0.9c0.2,0.2,0.4,0.2,0.6,0l6.2-5.8c0.2-0.2,0.2-0.4,0-0.6l-6.1-6.1C10.4,0.1,10.2,0.1,10,0.2z" fill="currentColor"></path>
{% endif %}
</svg>
<span class="content-pagination__link-text">
{{ contentPaginationItem.text }}
</span>
</span>
<span class="content-pagination__link-divider u-vh">{{ contentPaginationItem.bridgingText | default("page in this guide is:") }}</span>
<span class="content-pagination__link-label">{{ contentPaginationItem.label }}</span>
</a>
</li>
{% endfor %}
</ul>
</nav>
{% endmacro %}
.content-pagination {
display: block;
margin: 1.5rem 0 2.5rem;
&__list {
list-style: none;
margin: 0;
padding: 0;
}
&__item {
margin: 0 0 1.5rem;
}
&__link {
display: inline-block;
text-decoration: none;
&:hover {
text-decoration: none;
.content-pagination__link-label {
text-decoration: underline solid $color-text-link-hover 2px;
}
}
&:focus {
text-decoration: none;
.content-pagination__link-label {
text-decoration: none;
}
}
}
&__link-icon {
height: 0.9rem;
width: 1.2rem;
}
&__link-title {
display: block;
}
&__link-text {
font-size: 1.2rem;
font-weight: 700;
line-height: normal;
margin: 0 0 0 0.5rem;
}
&__link-label {
display: inline-block;
font-size: 0.9rem;
margin: 0 0 0 2rem;
text-decoration: underline;
}
}
When to use this component
Pagination helps users to navigate between a large number of items that are distributed across multiple pages whenever there are too many items to show at once. This will be most useful in contexts such as table listings of data, search results, and directories.
What constitutes ‘too many’ for a user can be influenced by factors like:
- amount of data in each entry (consider and test cognitive load for users)
- system load times
- screen space
When the number of pages exceeds the maximum display limit, ellipsis (…) are used to truncate the remaining pages.
How to use this component
If the pagination component sits inline with other content on the page, then the pagination should be left aligned.
Research on this component
If you have conducted any user research using this component, please feed back your findings via the
Design System forum