Skip to main content
Components

Pagination

Help users navigate collections of numbered pages like search results.

Read the Design System guidance for pagination

Import

import * as Pagination from 'govuk-react/pagination';

Examples

Default

Code
<Pagination.Composite
  previousHref="#"
  nextHref="#"
>
  {(
    <>
      <Pagination.ItemComposite href="#" number={1} />
      <Pagination.ItemComposite href="#" number={2} current />
      <Pagination.ItemComposite href="#" number={3} />
    </>
  )}
</Pagination.Composite>

With ellipsis

Code
<Pagination.Composite
  previousHref="#"
  nextHref="#"
>
  {(
    <>
      <Pagination.ItemComposite href="#" number={1} />
      <Pagination.ItemComposite ellipsis />
      <Pagination.ItemComposite href="#" number={6} />
      <Pagination.ItemComposite href="#" number={7} current />
      <Pagination.ItemComposite href="#" number={8} />
      <Pagination.ItemComposite ellipsis />
      <Pagination.ItemComposite href="#" number={42} />
    </>
  )}
</Pagination.Composite>

First page

Code
<Pagination.Composite nextHref="#">
  {(
    <>
      <Pagination.ItemComposite href="#" number={1} current />
      <Pagination.ItemComposite href="#" number={2} />
      <Pagination.ItemComposite href="#" number={3} />
    </>
  )}
</Pagination.Composite>

Last page

Code
<Pagination.Composite previousHref="#">
  {(
    <>
      <Pagination.ItemComposite href="#" number={1} />
      <Pagination.ItemComposite href="#" number={2} />
      <Pagination.ItemComposite href="#" number={3} current />
    </>
  )}
</Pagination.Composite>

For navigating between related pages

Code
<Pagination.Composite
  previousHref="#"
  previousText="Previous page"
  previousLabel="Applying for a provisional lorry or bus licence"
  nextHref="#"
  nextText="Next page"
  nextLabel="Driver CPC part 1 test: theory"
/>

With react router

Code
<MemoryRouter>
  <Pagination.Root>
    <Pagination.Previous>
      <Pagination.PreviousLink asChild>
        <RouterLink to="/page-1">
          <Pagination.PreviousIcon /> <Pagination.PreviousLinkTitleComposite />
        </RouterLink>
      </Pagination.PreviousLink>
    </Pagination.Previous>
    <Pagination.List>
      <Pagination.Item>
        <Pagination.ItemLink asChild aria-label="Page 1">
          <RouterLink to="/page-1">1</RouterLink>
        </Pagination.ItemLink>
      </Pagination.Item>
      <Pagination.Item current>
        <Pagination.ItemLink asChild aria-label="Page 2" aria-current="page">
          <RouterLink to="/page-2">2</RouterLink>
        </Pagination.ItemLink>
      </Pagination.Item>
      <Pagination.Item>
        <Pagination.ItemLink asChild aria-label="Page 3">
          <RouterLink to="/page-3">3</RouterLink>
        </Pagination.ItemLink>
      </Pagination.Item>
    </Pagination.List>
    <Pagination.Next>
      <Pagination.NextLink asChild>
        <RouterLink to="/page-3">
          <Pagination.NextLinkTitleComposite /> <Pagination.NextIcon />
        </RouterLink>
      </Pagination.NextLink>
    </Pagination.Next>
  </Pagination.Root>
</MemoryRouter>

API reference

Pagination.Root

Help users navigate collections of numbered pages like search results.

PropType
blockboolean

Pagination.Composite

Help users navigate collections of numbered pages like search results.

PropType
previousHref

The previous page's URL.

string
previousText

The text content of the link to the previous page. Defaults to "Previous page", with 'page' being visually hidden.

ReactNode
previousLabel

The optional label that goes underneath the link to the previous page, providing further context for the user about where the link goes.

ReactNode
nextHref

The next page's URL.

string
nextText

The text content of the link to the next page. Defaults to "Next page", with 'page' being visually hidden.

ReactNode
nextLabel

The optional label that goes underneath the link to the next page, providing further context for the user about where the link goes.

ReactNode
items

Prefer children, which memoise and re-render better.

ItemCompositeProps[]

Pagination.Item

PropType
currentboolean
ellipsisboolean

Pagination.ItemComposite

PropType
asChild

Render the only child (such as a router's link) instead of an a, with the link classes merged onto it.

boolean
number

The pagination item text – usually a page number. Required unless the item is an ellipsis.

string | number
current

Set to true to indicate the current page the user is on.

boolean
ellipsis

Use this option if you want to specify an ellipsis at a given point between numbers. If you set this option as true, any other options for the item are ignored.

boolean
PropType
asChild

Render the only child (such as a router's link) instead of an a, with the link classes merged onto it.

boolean
PropType
asChild

Render the only child (such as a router's link) instead of an a, with the link classes merged onto it.

boolean

Pagination.LinkLabel

No props of its own. Other props are passed to the element it renders.

Pagination.LinkTitle

PropType
decoratedboolean

Pagination.List

No props of its own. Other props are passed to the element it renders.

Pagination.Next

No props of its own. Other props are passed to the element it renders.

Pagination.NextIcon

No props of its own. Other props are passed to the element it renders.

PropType
asChild

Render the only child (such as a router's link) instead of an a, with the link classes merged onto it.

boolean

Pagination.NextLinkTitleComposite

PropType
decoratedboolean

Pagination.Previous

No props of its own. Other props are passed to the element it renders.

Pagination.PreviousIcon

No props of its own. Other props are passed to the element it renders.

PropType
asChild

Render the only child (such as a router's link) instead of an a, with the link classes merged onto it.

boolean

Pagination.PreviousLinkTitleComposite

PropType
decoratedboolean