Advertising sustains the DA. Ads are hidden for members. Join today

On this page

Customising Twig template files

Last updated on
13 August 2024

Out of the box, this theme has no styling for the pager:

The GOV.UK design system component for pagination is styled like this:

The first step is to locate the relevant Twig file. Ensure that you have Twig debugging enabled and then right click on any part of the pager and select 'Inspect'. In your browser's development console you will something like this:

This tells us that the Twig file we need to modify is core/modules/system/templates/pager.html.twig. Copy this file into your sub-theme's templates folder.

Next we need to navigate to GOV.UK Design Sytem Components page and select the Pagination item. Click the HTML option to view the pagination HTML with all the relevant classes that we will need to add to pager.html.twig. This HTML is shown below:

<nav class="govuk-pagination" aria-label="Pagination">
  <div class="govuk-pagination__prev">
    <a class="govuk-link govuk-pagination__link" href="#" rel="prev">
      <svg class="govuk-pagination__icon govuk-pagination__icon--prev" xmlns="http://www.w3.org/2000/svg" height="13" width="15" aria-hidden="true" focusable="false" viewBox="0 0 15 13">
        <path d="m6.5938-0.0078125-6.7266 6.7266 6.7441 6.4062 1.377-1.449-4.1856-3.9768h12.896v-2h-12.984l4.2931-4.293-1.414-1.414z"></path>
      </svg>
      <span class="govuk-pagination__link-title">
        Previous<span class="govuk-visually-hidden"> page</span>
      </span>
    </a>
  </div>
  <ul class="govuk-pagination__list">
    <li class="govuk-pagination__item">
      <a class="govuk-link govuk-pagination__link" href="#" aria-label="Page 1">
        1
      </a>
    </li>
    <li class="govuk-pagination__item govuk-pagination__item--current">
      <a class="govuk-link govuk-pagination__link" href="#" aria-label="Page 2" aria-current="page">
        2
      </a>
    </li>
    <li class="govuk-pagination__item">
      <a class="govuk-link govuk-pagination__link" href="#" aria-label="Page 3">
        3
      </a>
    </li>
  </ul>
  <div class="govuk-pagination__next">
    <a class="govuk-link govuk-pagination__link" href="#" rel="next">
      <span class="govuk-pagination__link-title">
        Next<span class="govuk-visually-hidden"> page</span>
      </span>
      <svg class="govuk-pagination__icon govuk-pagination__icon--next" xmlns="http://www.w3.org/2000/svg" height="13" width="15" aria-hidden="true" focusable="false" viewBox="0 0 15 13">
        <path d="m8.107-0.0078125-1.4136 1.414 4.2926 4.293h-12.986v2h12.896l-4.1855 3.9766 1.377 1.4492 6.7441-6.4062-6.7246-6.7266z"></path>
      </svg>
    </a>
  </div>
</nav>

Next open the pager.html.twig file from your sub-theme templates folder. Below is the relevant section of pager.html.twig

<ul class="pager__items js-pager__items">
  {# Print first item if we are not on the first page. #}
  {% if items.first %}
    <li class="pager__item pager__item--first">
      <a href="{{ items.first.href }}" title="{{ 'Go to first page'|t }}"{{ items.first.attributes|without('href', 'title') }}>
        <span class="visually-hidden">{{ 'First page'|t }}</span>
        <span aria-hidden="true">{{ items.first.text|default('« First'|t) }}</span>
      </a>
    </li>
  {% endif %}
  {# Print previous item if we are not on the first page. #}
  {% if items.previous %}
    <li class="pager__item pager__item--previous">
      <a href="{{ items.previous.href }}" title="{{ 'Go to previous page'|t }}" rel="prev"{{ items.previous.attributes|without('href', 'title', 'rel') }}>
        <span class="visually-hidden">{{ 'Previous page'|t }}</span>
        <span aria-hidden="true">{{ items.previous.text|default('‹ Previous'|t) }}</span>
      </a>
    </li>
  {% endif %}
  {# Add an ellipsis if there are further previous pages. #}
  {% if ellipses.previous %}
    <li class="pager__item pager__item--ellipsis" role="presentation">&hellip;</li>
  {% endif %}
  {# Now generate the actual pager piece. #}
  {% for key, item in items.pages %}
    <li class="pager__item{{ current == key ? ' is-active' : '' }}">
      {% if current == key %}
        {% set title = 'Current page'|t %}
      {% else %}
        {% set title = 'Go to page @key'|t({'@key': key}) %}
      {% endif %}
      <a href="{{ item.href }}" title="{{ title }}"{{ item.attributes|without('href', 'title') }}>
        <span class="visually-hidden">
          {{ 'Page'|t }}
        </span>
        {{- key -}}
      </a>
    </li>
  {% endfor %}
  {# Add an ellipsis if there are further next pages. #}
  {% if ellipses.next %}
    <li class="pager__item pager__item--ellipsis" role="presentation">&hellip;</li>
  {% endif %}
  {# Print next item if we are not on the last page. #}
  {% if items.next %}
    <li class="pager__item pager__item--next">
      <a href="{{ items.next.href }}" title="{{ 'Go to next page'|t }}" rel="next"{{ items.next.attributes|without('href', 'title', 'rel') }}>
        <span class="visually-hidden">{{ 'Next page'|t }}</span>
        <span aria-hidden="true">{{ items.next.text|default('Next ›'|t) }}</span>
      </a>
    </li>
  {% endif %}
  {# Print last item if we are not on the last page. #}
  {% if items.last %}
    <li class="pager__item pager__item--last">
      <a href="{{ items.last.href }}" title="{{ 'Go to last page'|t }}"{{ items.last.attributes|without('href', 'title') }}>
        <span class="visually-hidden">{{ 'Last page'|t }}</span>
        <span aria-hidden="true">{{ items.last.text|default('Last »'|t) }}</span>
      </a>
    </li>
  {% endif %}
</ul>

Guide: Applying Changes to the pager.html.twig file for Pagination

Overview

This guide explains the changes made to the pager.html.twig Twig template for pagination. The changes involve adding new classes to align with the GOV.UK Design System, ensuring a more accessible and standardized user interface.

Changes in the Twig File

Modification of the <ul> Element

Before:

<ul class="pager__items js-pager__items">

After:

<ul class="pager__items js-pager__items govuk-pagination__list">

Explanation: The class govuk-pagination__list has been added to the <ul> element to apply the GOV.UK Design System styling.

Modification of List Items (First Page)

Before:

<li class="pager__item pager__item--first">

After:

<li class="pager__item pager__item--first govuk-pagination__item pager__item">

Explanation: The class govuk-pagination__item has been added to the <li> element to apply the GOV.UK Design System styling.

Modification of List Items (Previous Page)

Before:

<li class="pager__item pager__item--previous">

After:

<li class="pager__item pager__item--previous govuk-pagination__item pager__item">

Explanation: The class govuk-pagination__item has been added to the <li> element to apply the GOV.UK Design System styling.

Modification of Ellipses (Previous)

Before:

<li class="pager__item pager__item--ellipsis" role="presentation">&hellip;</li>

After:

<li class="pager__item pager__item--ellipsis govuk-pagination__item" role="presentation">&hellip;</li>

Explanation: The class govuk-pagination__item has been added to the <li> element to apply the GOV.UK Design System styling.

Modification of Pages Loop

Before:

<li class="pager__item{{ current == key ? ' is-active' : '' }}">

After:

<li class="govuk-pagination__item pager__item{{ current == key ? ' is-active govuk-pagination__item--current' : '' }}">

Explanation:

  • The class govuk-pagination__item has been added to the <li> element.
  • If the current page is active, the class govuk-pagination__item--current is also added.

Anchor Tag (Within Pages Loop)

Before:

<a href="{{ item.href }}" title="{{ title }}"{{ item.attributes|without('href', 'title') }}>

After:

<a class="govuk-link govuk-pagination__link" href="{{ item.href }}" title="{{ title }}"{{ item.attributes|without('href', 'title') }} aria-label="Page {{ key }}" {{ current == key ? 'aria-current="page"' : '' }}>

Explanation:

  • Added govuk-link govuk-pagination__link classes to the <a> element.
  • Added aria-label attribute to improve accessibility.
  • Added aria-current="page" attribute for the current page to improve accessibility.

Modification of Ellipses (Next)

Before:

<li class="pager__item pager__item--ellipsis" role="presentation">&hellip;</li>

After:

<li class="pager__item pager__item--ellipsis govuk-pagination__item" role="presentation">&hellip;</li>

Explanation: The class govuk-pagination__item has been added to the <li> element to apply the GOV.UK Design System styling.

Modification of List Items (Last Page)

Before:

<li class="pager__item pager__item--last">

After:

<li class="pager__item pager__item--last govuk-pagination__item pager__item">

Explanation: The class govuk-pagination__item has been added to the <li> element to apply the GOV.UK Design System styling.

Summary

The main changes involve adding GOV.UK Design System classes (govuk-pagination__item, govuk-link, govuk-pagination__link, etc.) to the existing elements to ensure a consistent and accessible design. Additionally, attributes like aria-label and aria-current are added to improve accessibility.

By following these changes, the pagination will now have a standardized and accessible design that aligns with the GOV.UK Design System.

Below is the modified section of pager.html.twig

<ul class="pager__items js-pager__items govuk-pagination__list">
	{# Print first item if we are not on the first page. #}
	{% if items.first %}
		<li class="pager__item pager__item--first govuk-pagination__item pager__item">
		<a href="{{ items.first.href }}" title="{{ 'Go to first page'|t }}"{{ items.first.attributes|without('href', 'title') }}>
			<span class="visually-hidden">{{ 'First page'|t }}</span>
			<span aria-hidden="true">{{ items.first.text|default('« First'|t) }}</span>
		</a>
		</li>
	{% endif %}
	{# Print previous item if we are not on the first page. #}
	{% if items.previous %}
		<li class="pager__item pager__item--previous govuk-pagination__item pager__item">
		<a href="{{ items.previous.href }}" title="{{ 'Go to previous page'|t }}" rel="prev"{{ items.previous.attributes|without('href', 'title', 'rel') }}>
			<span class="visually-hidden">{{ 'Previous page'|t }}</span>
			<span aria-hidden="true">{{ items.previous.text|default('‹ Previous'|t) }}</span>
		</a>
		</li>
	{% endif %}
	{# Add an ellipsis if there are further previous pages. #}
	{% if ellipses.previous %}
		<li class="pager__item pager__item--ellipsis govuk-pagination__item" role="presentation">&hellip;</li>
	{% endif %}
	{# Now generate the actual pager piece. #}
	{% for key, item in items.pages %}
		<li class="govuk-pagination__item pager__item{{ current == key ? ' is-active govuk-pagination__item--current' : '' }}">
		{% if current == key %}
			{% set title = 'Current page'|t %}
		{% else %}
			{% set title = 'Go to page @key'|t({'@key': key}) %}
		{% endif %}
		<a class="govuk-link govuk-pagination__link" href="{{ item.href }}" title="{{ title }}"{{ item.attributes|without('href', 'title') }} aria-label="Page {{ key }}" {{ current == key ? 'aria-current="page"' : '' }}>
			<span class="visually-hidden">
			{{ 'Page'|t }}
			</span>
			{{- key -}}
		</a>
		</li>
	{% endfor %}
	{# Add an ellipsis if there are further next pages. #}
	{% if ellipses.next %}
		<li class="pager__item pager__item--ellipsis govuk-pagination__item" role="presentation">&hellip;</li>
	{% endif %}
	{# Print next item if we are not on the last page. #}
	{% if items.next %}
		<li class="pager__item pager__item--next govuk-pagination__item pager__item">
		<a href="{{ items.next.href }}" title="{{ 'Go to next page'|t }}" rel="next"{{ items.next.attributes|without('href', 'title', 'rel') }}>
			<span class="visually-hidden">{{ 'Next page'|t }}</span>
			<span aria-hidden="true">{{ items.next.text|default('Next ›'|t) }}</span>
		</a>
		</li>
	{% endif %}
	{# Print last item if we are not on the last page. #}
	{% if items.last %}
		<li class="pager__item pager__item--last govuk-pagination__item pager__item">
		<a href="{{ items.last.href }}" title="{{ 'Go to last page'|t }}"{{ items.last.attributes|without('href', 'title') }}>
			<span class="visually-hidden">{{ 'Last page'|t }}</span>
			<span aria-hidden="true">{{ items.last.text|default('Last »'|t) }}</span>
		</a>
		</li>
	{% endif %}
</ul>

Save your changes to pager.html.twig and issue a 'drush cr' so Drupal picks up this new template file. Navigate to a page with a pager and you should now see:

If you have modified a Twig template file to the GOV.UK Design System, let us know about it so we can include it in a future release of this theme.

Related Content

Create a sub theme

Create a sub theme of the GOV.UK theme

Help improve this page

Page status: No known problems

You can: