Component

Pagination

Navigational links that allow users to navigate within a series of pages or elements.

This component accepts 3 optional parameters: previous, next and items.

The next and previous parameters accept:

an URL for the link
a title for the URL
a label that can add extra info (ie page number) that will be displayed under the title

If one of the 2 parameters is nil, no link will appear.

The item parameter accepts an array of objects with the following parameters:

an href for the link
a number of the page (required if ellipsis not set)
current, if set then the item will be styled as the current page
ellipsis, if set then the item will not be a link but will be a seperator with the text of “…”
visually hidden text, which will override the default aria label of the page link (Page NUMBER)

For more guidance on best practice, please refer to the GOV.UK Design System’s Pagination guidance.

Search for usage of this component on GitHub.

How it looks (preview) (preview all)

How to call this component

<%= render "govuk_publishing_components/components/pagination", {
  previous_page: {
    href: "previous-page",
    title: "Previous page",
    label: "1 of 3",
    icon: sanitize("  <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>
    ")
  }
} %>

Accessibility acceptance criteria

Icons in the component must not be announced by screen readers.

The component must:

identify itself as pagination navigation
provide a distinction between the navigation text and label text of the links both visually and for screenreaders

Links in the component must:

accept focus
be focusable with a keyboard
be usable with a keyboard
indicate when they have focus
change in appearance when touched (in the touch-down state)
change in appearance when hovered
be usable with touch
be usable with voice commands
have visible text
have meaningful text

Other examples

Standard options

This component uses the component wrapper helper. It accepts the following options and applies them to the parent element of the component. See the component wrapper helper documentation for more detail.

id - accepts a string for the element ID attribute
data_attributes - accepts a hash of data attributes
aria - accepts a hash of aria attributes
classes - accepts a space separated string of classes, these should not be used for styling and must be prefixed with js-
margin_bottom - accepts a number from 0 to 9 (0px to 60px) using the GOV.UK Frontend spacing scale
role - accepts a space separated string of roles
lang - accepts a language attribute value
open - accepts an open attribute value (true or false)
hidden - accepts an empty string, ‘hidden’, or ‘until-found’
tabindex - accepts an integer. The integer can also be passed as a string
dir - accepts ‘rtl’, ‘ltr’, or ‘auto’
type - accepts any valid type attribute e.g. ‘button’, ‘submit’, ‘text’
rel - accepts any valid rel attribute e.g. ‘nofollow’
target - accepts a valid target attribute e.g. ‘_blank’
title - accepts any string
draggable - accepts a draggable attribute value (“true” or “false”)

Only next (preview)

<%= render "govuk_publishing_components/components/pagination", {
  next_page: {
    href: "next-page",
    title: "Next page",
    label: "Tax disc"
  }
} %>

Both previous and next (preview)

<%= render "govuk_publishing_components/components/pagination", {
  previous_page: {
    href: "previous-page",
    title: "Previous page",
    label: "1 of 3"
  },
  next_page: {
    href: "next-page",
    title: "Next page",
    label: "3 of 3"
  }
} %>

Both previous and next no labels (preview)

<%= render "govuk_publishing_components/components/pagination", {
  previous_page: {
    href: "previous-page",
    title: "Previous page"
  },
  next_page: {
    href: "next-page",
    title: "Next page"
  }
} %>

Become a lorry bus driver example (preview)

<%= render "govuk_publishing_components/components/pagination", {
  previous_page: {
    href: "previous-page",
    title: "Previous",
    label: "Applying for a provisional lorry or bus licence"
  },
  next_page: {
    href: "next-page",
    title: "Next",
    label: "Driver CPC part 1 test: theory"
  }
} %>

Without ga4 tracking (preview)

Disables the GA4 link tracker on the links. Tracking is enabled by default.

<%= render "govuk_publishing_components/components/pagination", {
  disable_ga4: true,
  previous_page: {
    href: "previous-page",
    title: "Previous",
    label: "Applying for a provisional lorry or bus licence"
  },
  next_page: {
    href: "next-page",
    title: "Next",
    label: "Driver CPC part 1 test: theory"
  }
} %>

Both previous and next with items (preview)

<%= render "govuk_publishing_components/components/pagination", {
  previous_page: {
    href: "previous-page"
  },
  next_page: {
    href: "next-page"
  },
  items: [
    {
      number: 1,
      href: "#"
    },
    {
      ellipsis: true
    },
    {
      number: 6,
      href: "#"
    },
    {
      number: 7,
      href: "#",
      current: true
    },
    {
      number: 8,
      href: "#"
    },
    {
      ellipsis: true
    },
    {
      number: 42,
      href: "#"
    }
  ]
} %>

Next with items (preview)

<%= render "govuk_publishing_components/components/pagination", {
  next_page: {
    href: "next-page"
  },
  items: [
    {
      number: 1,
      href: "#",
      current: true
    },
    {
      number: 2,
      href: "#"
    },
    {
      number: 3,
      href: "#"
    }
  ]
} %>

Previous with items (preview)

<%= render "govuk_publishing_components/components/pagination", {
  previous_page: {
    href: "next-page"
  },
  items: [
    {
      number: 1,
      href: "#"
    },
    {
      number: 2,
      href: "#"
    },
    {
      number: 3,
      href: "#",
      current: true
    }
  ]
} %>