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 hods-pagination__navigation__link hods-pagination__navigation__link--current"
          href=""
        >
          1
        </a>
      </li>
      <li class="hods-pagination__navigation__item">
        <a
          class="govuk-link hods-pagination__navigation__link"
          aria-label="Go to page 1"
          href="/?page=2"
        >
          2
        </a>
      </li>
      <li class="hods-pagination__navigation__item">
        <a
          class="govuk-link hods-pagination__navigation__link"
          aria-label="Go to page 1"
          href="/?page=3"
        >
          3
        </a>
      </li>
      <li class="hods-pagination__navigation__item">
        <a
          class="govuk-link hods-pagination__navigation__link"
          aria-label="Next page, go to page 2"
          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 string 'id' attribute to place on the base HTML element
classBlock string Block name override in BEM style classes applied to all elements
classModifiers other BEM style modifiers to apply to the base HTML element
className string Extra classes to apply to the base HTML element
size number Number of items to be shown on each page
pageParameter string 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 hods-pagination__navigation__link hods-pagination__navigation__link--current"
          href=""
        >
          1
        </a>
      </li>
      <li class="hods-pagination__navigation__item">
        <a
          class="govuk-link hods-pagination__navigation__link"
          aria-label="Go to page 1"
          href="/?page=2"
        >
          2
        </a>
      </li>
      <li class="hods-pagination__navigation__item">
        <a
          class="govuk-link hods-pagination__navigation__link"
          aria-label="Go to page 1"
          href="/?page=3"
        >
          3
        </a>
      </li>
      <li class="hods-pagination__navigation__item">
        <a
          class="govuk-link hods-pagination__navigation__link"
          aria-label="Next page, go to page 2"
          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 hods-pagination__navigation__link hods-pagination__navigation__link--current"
          href=""
        >
          1
        </a>
      </li>
      <li class="hods-pagination__navigation__item">
        <a
          class="govuk-link hods-pagination__navigation__link"
          aria-label="Go to page 1"
          href="/?page=2"
        >
          2
        </a>
      </li>
      <li class="hods-pagination__navigation__item">
        <a
          class="govuk-link hods-pagination__navigation__link"
          aria-label="Go to page 1"
          href="/?page=3"
        >
          3
        </a>
      </li>
      <li class="hods-pagination__navigation__item">
        <a
          class="govuk-link hods-pagination__navigation__link"
          aria-label="Next page, go to page 2"
          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.

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 hods-pagination__navigation__link hods-pagination__navigation__link--current"
          href=""
        >
          1
        </a>
      </li>
      <li class="hods-pagination__navigation__item">
        <a
          class="govuk-link hods-pagination__navigation__link"
          aria-label="Go to page 1"
          href="/?p=2"
        >
          2
        </a>
      </li>
      <li class="hods-pagination__navigation__item">
        <a
          class="govuk-link hods-pagination__navigation__link"
          aria-label="Go to page 1"
          href="/?p=3"
        >
          3
        </a>
      </li>
      <li class="hods-pagination__navigation__item">
        <a
          class="govuk-link hods-pagination__navigation__link"
          aria-label="Next page, go to page 2"
          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:

To contribute, add your thoughts and research findings to our GitHub discussion, or follow our contribute guidance.