Components
Pagination
A component for navigating a long list of results.
1
2
3
4
5
6
7
8
9
10
<div class="hods-pagination">
<div class="hods-pagination__content">
<div>1</div>
<div>2</div>
<div>3</div>
<div>4</div>
<div>5</div>
<div>6</div>
<div>7</div>
<div>8</div>
<div>9</div>
<div>10</div>
</div>
<nav
class="hods-pagination__navigation"
role="navigation"
aria-label="Pagination Navigation"
>
<div class="hods-pagination__navigation__summary">
Showing 1 - 10 of 30 results
</div>
<ul
class="hods-pagination__navigation__list-items"
>
<li class="hods-pagination__navigation__item">
<a
aria-current="true"
aria-label="Current page, page 1"
class="govuk-link govuk-link--active hods-pagination__navigation__link hods-pagination__navigation__link--current"
href=""
>
1
</a>
</li>
<li class="hods-pagination__navigation__item">
<a
aria-label="Go to page 2"
class="govuk-link hods-pagination__navigation__link"
href="/?page=2"
>
2
</a>
</li>
<li class="hods-pagination__navigation__item">
<a
aria-label="Go to page 3"
class="govuk-link hods-pagination__navigation__link"
href="/?page=3"
>
3
</a>
</li>
<li class="hods-pagination__navigation__item">
<a
aria-label="Next page, go to page 2"
class="govuk-link hods-pagination__navigation__link"
href="/?page=2"
>
Next
<span
aria-hidden="true"
role="presentation"
>
»
</span>
</a>
</li>
</ul>
</nav>
</div>
<Pagination>
<div>1</div>
<div>2</div>
<div>3</div>
<div>4</div>
<div>5</div>
<div>6</div>
<div>7</div>
<div>8</div>
<div>9</div>
<div>10</div>
<div>11</div>
<div>12</div>
<div>13</div>
<div>14</div>
<div>15</div>
<div>16</div>
<div>17</div>
<div>18</div>
<div>19</div>
<div>20</div>
<div>21</div>
<div>22</div>
<div>23</div>
<div>24</div>
<div>25</div>
<div>26</div>
<div>27</div>
<div>28</div>
<div>29</div>
<div>30</div>
</Pagination>
Props
| Name | Type | Default | Description |
|---|---|---|---|
| id | other | 'id' attribute to place on the base HTML element | |
| classBlock | other | Block name override in BEM style classes applied to all elements | |
| classModifiers | other | BEM style modifiers to apply to the base HTML element | |
| className | other | Extra classes to apply to the base HTML element | |
| size | other | Number of items to be shown on each page | |
| pageParameter | other | Query parameter to use for the page number |
When to use this component
Design so you don’t need pagination as it hides content from the user. It can display a lot of unhelpful information that gets in the way to what the users are looking for. This may indicate the design isn’t working.
You can avoid pagination by:
- setting the default number of results per page (try 50 items per page, although do test with users to get it right for that service)
- avoid infinite scrolling as this is problematic for keyboard-only users
Consider what the sorting order should be to make the search more relevant. The more specific it is to the user's search criteria, the better the search results.
How it works
Standard pagination
1
2
3
4
5
6
7
8
9
10
<div class="hods-pagination">
<div class="hods-pagination__content">
<div>1</div>
<div>2</div>
<div>3</div>
<div>4</div>
<div>5</div>
<div>6</div>
<div>7</div>
<div>8</div>
<div>9</div>
<div>10</div>
</div>
<nav
class="hods-pagination__navigation"
role="navigation"
aria-label="Pagination Navigation"
>
<div class="hods-pagination__navigation__summary">
Showing 1 - 10 of 30 results
</div>
<ul
class="hods-pagination__navigation__list-items"
>
<li class="hods-pagination__navigation__item">
<a
aria-current="true"
aria-label="Current page, page 1"
class="govuk-link govuk-link--active hods-pagination__navigation__link hods-pagination__navigation__link--current"
href=""
>
1
</a>
</li>
<li class="hods-pagination__navigation__item">
<a
aria-label="Go to page 2"
class="govuk-link hods-pagination__navigation__link"
href="/?page=2"
>
2
</a>
</li>
<li class="hods-pagination__navigation__item">
<a
aria-label="Go to page 3"
class="govuk-link hods-pagination__navigation__link"
href="/?page=3"
>
3
</a>
</li>
<li class="hods-pagination__navigation__item">
<a
aria-label="Next page, go to page 2"
class="govuk-link hods-pagination__navigation__link"
href="/?page=2"
>
Next
<span
aria-hidden="true"
role="presentation"
>
»
</span>
</a>
</li>
</ul>
</nav>
</div>
<Pagination>
<div>1</div>
<div>2</div>
<div>3</div>
<div>4</div>
<div>5</div>
<div>6</div>
<div>7</div>
<div>8</div>
<div>9</div>
<div>10</div>
<div>11</div>
<div>12</div>
<div>13</div>
<div>14</div>
<div>15</div>
<div>16</div>
<div>17</div>
<div>18</div>
<div>19</div>
<div>20</div>
<div>21</div>
<div>22</div>
<div>23</div>
<div>24</div>
<div>25</div>
<div>26</div>
<div>27</div>
<div>28</div>
<div>29</div>
<div>30</div>
</Pagination>
Results per page
Display a different number of results per page.
1
2
3
4
5
<div class="hods-pagination">
<div class="hods-pagination__content">
<div>1</div>
<div>2</div>
<div>3</div>
<div>4</div>
<div>5</div>
</div>
<nav
class="hods-pagination__navigation"
role="navigation"
aria-label="Pagination Navigation"
>
<div class="hods-pagination__navigation__summary">
Showing 1 - 5 of 30 results
</div>
<ul
class="hods-pagination__navigation__list-items"
>
<li class="hods-pagination__navigation__item">
<a
aria-current="true"
aria-label="Current page, page 1"
class="govuk-link govuk-link--active hods-pagination__navigation__link hods-pagination__navigation__link--current"
href=""
>
1
</a>
</li>
<li class="hods-pagination__navigation__item">
<a
aria-label="Go to page 2"
class="govuk-link hods-pagination__navigation__link"
href="/?page=2"
>
2
</a>
</li>
<li class="hods-pagination__navigation__item">
<a
aria-label="Go to page 3"
class="govuk-link hods-pagination__navigation__link"
href="/?page=3"
>
3
</a>
</li>
<li class="hods-pagination__navigation__item">
<a
aria-label="Next page, go to page 2"
class="govuk-link hods-pagination__navigation__link"
href="/?page=2"
>
Next
<span
aria-hidden="true"
role="presentation"
>
»
</span>
</a>
</li>
</ul>
</nav>
</div>
<Pagination size={5}>
<div>1</div>
<div>2</div>
<div>3</div>
<div>4</div>
<div>5</div>
<div>6</div>
<div>7</div>
<div>8</div>
<div>9</div>
<div>10</div>
<div>11</div>
<div>12</div>
<div>13</div>
<div>14</div>
<div>15</div>
<div>16</div>
<div>17</div>
<div>18</div>
<div>19</div>
<div>20</div>
<div>21</div>
<div>22</div>
<div>23</div>
<div>24</div>
<div>25</div>
<div>26</div>
<div>27</div>
<div>28</div>
<div>29</div>
<div>30</div>
</Pagination>
Custom query parameter
Control the GET / query parameter used to set the active page with the pageParameter prop.
21
22
23
24
25
26
27
28
29
30
<div class="hods-pagination">
<div class="hods-pagination__content">
<div>1</div>
<div>2</div>
<div>3</div>
<div>4</div>
<div>5</div>
<div>6</div>
<div>7</div>
<div>8</div>
<div>9</div>
<div>10</div>
</div>
<nav
class="hods-pagination__navigation"
role="navigation"
aria-label="Pagination Navigation"
>
<div class="hods-pagination__navigation__summary">
Showing 1 - 10 of 30 results
</div>
<ul
class="hods-pagination__navigation__list-items"
>
<li class="hods-pagination__navigation__item">
<a
aria-current="true"
aria-label="Current page, page 1"
class="govuk-link govuk-link--active hods-pagination__navigation__link hods-pagination__navigation__link--current"
href=""
>
1
</a>
</li>
<li class="hods-pagination__navigation__item">
<a
aria-label="Go to page 2"
class="govuk-link hods-pagination__navigation__link"
href="/?p=2"
>
2
</a>
</li>
<li class="hods-pagination__navigation__item">
<a
aria-label="Go to page 3"
class="govuk-link hods-pagination__navigation__link"
href="/?p=3"
>
3
</a>
</li>
<li class="hods-pagination__navigation__item">
<a
aria-label="Next page, go to page 2"
class="govuk-link hods-pagination__navigation__link"
href="/?p=2"
>
Next
<span
aria-hidden="true"
role="presentation"
>
»
</span>
</a>
</li>
</ul>
</nav>
</div>
<Pagination pageParameter="p">
<div>1</div>
<div>2</div>
<div>3</div>
<div>4</div>
<div>5</div>
<div>6</div>
<div>7</div>
<div>8</div>
<div>9</div>
<div>10</div>
<div>11</div>
<div>12</div>
<div>13</div>
<div>14</div>
<div>15</div>
<div>16</div>
<div>17</div>
<div>18</div>
<div>19</div>
<div>20</div>
<div>21</div>
<div>22</div>
<div>23</div>
<div>24</div>
<div>25</div>
<div>26</div>
<div>27</div>
<div>28</div>
<div>29</div>
<div>30</div>
</Pagination>
Accessibility
If you do require pagination, ensure that:
- large clickable hit areas are provided and are clearly spaced out
- the current page is clearly identified
- you set a maximum list of 5 pages
- you provide 'previous' and 'next' links. Don't rely on icons alone
Research
If your service uses this component, let us know of any insights you have on research.
Help improve this component
This component needs improving. We need evidence about:
- how to write for this component
- which services are using this component
- if it duplicates the pagination component in the GOV.UK design system
To contribute, add your thoughts and research findings to our GitHub discussion, or follow our contribute guidance.