Pagination
Basic pagination
This style of pagination is suitable for usage when the number of pages is relatively small. It does not indicate the total number of pages there are for the current context or query.
Demo
Select a page from the dropdown to see how the pagination component is displayed based on the selected page. Assume there are a total of 8 pages.
Code
The following code example sets the current page to 2 to show each of the pagination components.
<!-- Add a descriptive label for screen readers.
E.g. If the pagination is for search results, the value can be "Search results pagination" -->
<nav aria-label="{{ Label for Assistive Technology users }}">
<!-- The `justify-content-center` class provides center-alignment -->
<ul class="pagination {{ justify-content-center }}">
<!-- Previous page link -->
<li class="page-item prev">
<a class="page-link" href="{{ URL }}">
<span class="cui cicon-angle-left left" aria-hidden="true"></span>
<span class="text">Prev</span>
</a>
</li>
<!-- Numerical page items -->
<!-- Mark the current page with the `active` class -->
<!-- Mark the other numerical items with the `inactive` class -->
<li class="page-item inactive">
<a class="page-link" href="{{ URL }}">1</a>
</li>
<li class="page-item active">
<a class="page-link" href="{{ URL }}">2</a>
</li>
<li class="page-item inactive">
<a class="page-link" href="{{ URL }}">3</a>
</li>
<li class="page-item inactive">
<a class="page-link" href="{{ URL }}">4</a>
</li>
<li class="page-item inactive">
<a class="page-link" href="{{ URL }}">5</a>
</li>
<!-- Next page link -->
<li class="page-item next">
<a class="page-link" href="{{ URL }}">
<span class="text">Next</span>
<span class="cui cicon-angle-right right" aria-hidden="true"></span>
</a>
</li>
</ul>
</nav>
Pagination with first and last page context
This style of pagination is suitable for usage when the number of pages has the potential to be lengthy. It displays the last page as a visual anchor to inform the user how many total pages there are for the current context or query.
Demo
Select a page from the dropdown to see how the pagination component is displayed based on the selected page. Assume there are a total of 20 pages.
Code
The following code example sets the current page to 5 to show each of the pagination components.
<!-- Add a descriptive label for screen readers.
E.g. If the pagination is for search results, the value can be "Search results pagination" -->
<nav aria-label="{{ Label for Assistive Technology users }}">
<!-- The `justify-content-center` class provides center-alignment -->
<ul class="pagination {{ justify-content-center }}">
<!-- Previous page link -->
<li class="page-item prev">
<a class="page-link" href="{{ URL }}">
<span class="cui cicon-angle-left left" aria-hidden="true"></span>
<span class="text">Prev</span>
</a>
</li>
<!-- First page item, always shown -->
<li class="page-item inactive">
<a class="page-link" href="{{ URL }}">1</a>
</li>
<!-- Filler page item, shows the gap between the current context and the first page -->
<li class="page-item text-only">
<span class="page-text">…</span>
</li>
<!-- Numerical page items -->
<!-- Mark the current page with the `active` class -->
<!-- Mark the other numerical items with the `inactive` class -->
<li class="page-item inactive">
<a class="page-link" href="{{ URL }}">4</a>
</li>
<li class="page-item active">
<a class="page-link" href="{{ URL }}">5</a>
</li>
<li class="page-item inactive">
<a class="page-link" href="{{ URL }}">6</a>
</li>
<!-- Filler page item, shows the gap between the current context and the last page -->
<li class="page-item text-only">
<span class="page-text">…</span>
</li>
<!-- Last page item, always shown -->
<li class="page-item inactive">
<a class="page-link" href="{{ URL }}">20</a>
</li>
<!-- Next page link -->
<li class="page-item next">
<a class="page-link" href="{{ URL }}">
<span class="text">Next</span>
<span class="cui cicon-angle-right right" aria-hidden="true"></span>
</a>
</li>
</ul>
</nav>
Horizontal alignment
By default, the pagination component is left-aligned. Change the horizontal alignment with the utility classes: justify-content-center for centre-alignment or justify-content-end for right-alignment.
Left-aligned
<nav aria-label="{{ Label for Assistive Technology users }}">
<ul class="pagination">
...
</ul>
</nav>
Centre-aligned
<nav aria-label="{{ Label for Assistive Technology users }}">
<ul class="pagination justify-content-center">
...
</ul>
</nav>
Right-aligned
<nav aria-label="{{ Label for Assistive Technology users }}">
<ul class="pagination justify-content-end">
...
</ul>
</nav>
Mobile variations
Mobile optimizations are built into the CSS by default. The filler context items (the inactive page items and the `…` span items) are hidden while leaving the active page and next/prev buttons visible.
Below are optional mobile modifier classes that can be applied to the <ul class="pagination"> element.
| Class name | Description |
|---|---|
mobile-hide-text |
Hides the text in the prev and next links for mobile only. |
mobile-show-all |
Shows the filler context elements hidden by default. Example: the inactive page items and the `…` span items. This class should only be used if it is necessary to show all of the pagination elements in mobile. |
Demo
mobile-hide-text
Resize your browser window to a mobile size to see the demo below.
The text in the prev and next links will be hidden in mobile.
<nav aria-label="{{ Label for Assistive Technology users }}">
<ul class="pagination mobile-hide-text">
...
</ul>
</nav>
mobile-show-all
Resize your browser window to a mobile size to see the demo below.
The filler context elements, hidden by default in mobile, will become visible.
<nav aria-label="{{ Label for Assistive Technology users }}">
<ul class="pagination mobile-show-all">
...
</ul>
</nav>