Pagination

A hand-drawn pager for splitting long lists across numbered pages.

Overview

Pagination splits a long list of results across numbered pages, with Previous/Next controls and an ellipsis that collapses large ranges. It is controlled — you own the current page and update it from onPageChange.

Anatomy

A <nav> landmark wrapping Previous, a run of numbered page buttons, and Next. Each button is a sketchy box (@ghds/sketch-core); the current page is filled and marked aria-current="page". Large gaps collapse to a single ellipsis, keeping the first, last, and the pages around the current one (siblingCount).

Variants & States

Usage

Accessibility

• React / Web Components: a <nav aria-label="Pagination"> landmark; each control is a real <button> with a descriptive aria-label (“Page 3”, “Previous page”); the current page carries aria-current="page". Web Components dispatches a page-change event.
• React Native: the row exposes role="navigation"; each control is accessibilityRole="button" with a label and accessibilityState (selected for the current page, disabled for the ends).
• Every control is keyboard-operable on the web platforms.

Content

Numeric page labels, plus “Previous”/“Next” accessible labels. No visible prose beyond the numbers and chevron icons.

Props API

Code examples

// React — @ghds/react
import { Pagination } from '@ghds/react/pagination';
import { useState } from 'react';

const [page, setPage] = useState(3);
<Pagination count={12} page={page} onPageChange={setPage} />;

<!-- Web Components — @ghds/web-components -->
<script type="module">
  import '@ghds/web-components/pagination';
</script>
<gh-pagination id="pager" count="12" page="3"></gh-pagination>
<script>
  const el = document.getElementById('pager');
  el.addEventListener('page-change', (e) => {
    el.page = e.detail;
  });
</script>

// React Native — @ghds/react-native
import { Pagination } from '@ghds/react-native/pagination';
import { useState } from 'react';

const [page, setPage] = useState(1);
<Pagination count={12} page={page} onPageChange={setPage} />;

Live Demo