Component

Pagination

Help users navigate forwards and backwards through a series of pages. For example, search results or guidance that’s divided into multiple website pages.

Search for usage of this component on GitHub.

How it looks (preview) (preview all)

How to call this component

<%= render "components/pagination", {
  previous_href: "/page/1",
  next_href: "/page/3",
  items: [
    {
      href: "/page/1"
    },
    {
      href: "/page/2",
      current: true
    },
    {
      href: "/page/3"
    }
  ]
} %>

Accessibility acceptance criteria

The component must:

• accept focus
• be focusable with a keyboard
• be usable with a keyboard
• be usable with touch
• indicate when they have focus
• be recognisable as form select elements
• have correctly associated labels

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

Without previous or next links (preview)

<%= render "components/pagination", {
  items: [
    {
      href: "/page/1"
    },
    {
      href: "/page/2"
    },
    {
      href: "/page/3"
    }
  ]
} %>

With selected item (preview)

<%= render "components/pagination", {
  items: [
    {
      href: "/page/1",
      current: true
    },
    {
      href: "/page/2"
    },
    {
      href: "/page/3"
    }
  ]
} %>

Without previous link (preview)

<%= render "components/pagination", {
  next_href: "/page/3",
  items: [
    {
      label: 1,
      href: "/page/1",
      current: true
    },
    {
      label: 2,
      href: "/page/2"
    },
    {
      label: 3,
      href: "/page/3"
    }
  ]
} %>

Without next link (preview)

<%= render "components/pagination", {
  previous_href: "/page/2",
  items: [
    {
      href: "/page/1"
    },
    {
      href: "/page/2"
    },
    {
      href: "/page/3",
      current: true
    }
  ]
} %>

With labels (preview)

<%= render "components/pagination", {
  previous_href: "/page/1",
  next_href: "/page/3",
  items: [
    {
      label: 1.1,
      href: "/page/1"
    },
    {
      label: 1.2,
      href: "/page/2",
      current: true
    },
    {
      label: 1.3,
      href: "/page/3"
    }
  ]
} %>

With custom aria label (preview)

<%= render "components/pagination", {
  aria_label: "Search results",
  previous_href: "/page/1",
  next_href: "/page/3",
  items: [
    {
      href: "/page/1"
    },
    {
      href: "/page/2",
      current: true
    },
    {
      href: "/page/3"
    }
  ]
} %>

With custom aria label for element (preview)

<%= render "components/pagination", {
  aria_label: "Search results with aria labels",
  previous_href: "/page/1.1",
  next_href: "/page/3.1",
  items: [
    {
      href: "/page/1.1",
      aria_label: "Page 1.1"
    },
    {
      href: "/page/2.1",
      current: true,
      aria_label: "Page 2.1"
    },
    {
      href: "/page/3.1",
      aria_label: "Page 3.1"
    }
  ]
} %>

With ellipses items (preview)

<%= render "components/pagination", {
  previous_href: "/page/1",
  next_href: "/page/3",
  items: [
    {
      label: 1,
      href: "/page/1"
    },
    {
      ellipses: true
    },
    {
      label: 20,
      href: "/page/20"
    },
    {
      label: 21,
      href: "/page/21",
      current: true
    },
    {
      label: 22,
      href: "/page/22"
    },
    {
      ellipses: true
    },
    {
      label: 100,
      href: "/page/100"
    }
  ]
} %>