Skip to content

Pagination

Move between pages of a long list, with a "Showing 21 to 40 of 312" line, as links or as buttons.

<nav class="cap-pagination" aria-label="Pagination" id="pg-middle">
  <p class="cap-pagination-status">Showing 41 to 60 of 312 posts</p>
  <ul class="cap-pagination-list">
    <li><a class="cap-page" data-kind="prev" href="#page-2" rel="prev">Previous</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 1" href="#page-1">1</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 2" href="#page-2">2</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 3" aria-current="page" href="#page-3">3</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 4" href="#page-4">4</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 5" href="#page-5">5</a></li>
    <li class="cap-pagination-num"><span class="cap-page-gap"><span aria-hidden="true">&hellip;</span><span class="cap-sr-only">More pages</span></span></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 16" href="#page-16">16</a></li>
    <li class="cap-pagination-where">Page 3 of 16</li>
    <li><a class="cap-page" data-kind="next" href="#page-4" rel="next">Next</a></li>
  </ul>
</nav>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/pagination.css";
import { enhance } from "capsomer/behavior/pagination";

enhance();

Usage

<nav class="cap-pagination" aria-label="Posts pages">
  <p class="cap-pagination-status">Showing 41 to 60 of 312 posts</p>
  <ul class="cap-pagination-list">
    <li><a class="cap-page" data-kind="prev" href="?page=2" rel="prev">Previous</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 1" href="?page=1">1</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 3" aria-current="page" href="?page=3">3</a></li>
    <li class="cap-pagination-num"><span class="cap-page-gap"><span aria-hidden="true">&hellip;</span><span class="cap-sr-only">More pages</span></span></li>
    <li class="cap-pagination-where">Page 3 of 16</li>
    <li><a class="cap-page" data-kind="next" href="?page=4" rel="next">Next</a></li>
  </ul>
</nav>
<nav class="cap-pagination" aria-label="Posts pages" data-cap="pagination"
     data-page="1" data-page-count="16" data-total="312" data-per-page="20" data-noun="posts">
<Pagination page={3} pageCount={16} total={312} perPage={20} noun="posts"
  hrefFor={(n) => `?page=${n}`} label="Posts pages" />

<Pagination page={page} pageCount={16} onPageChange={setPage} total={312} perPage={20} noun="posts" />
// A loader: read the address, keep it in range, query one page.
const { page, offset, perPage, pageCount, total } = pageEnvelope(parsePage(url.searchParams.get("page")), 25, count);
const hrefFor = (n: number) => pageHref("/admin/webhooks", { type, errors: errorsOnly }, n);
export const links = () => pageRelLinks(page, pageCount, hrefFor);

<Pagination form="steps" page={page} pageCount={pageCount} hrefFor={hrefFor} prevLabel="Newer" nextLabel="Older" label="Journal pages" />
<Pagination form="steps" page={page} pageCount={0} hasNext={rows.length > perPage} hrefFor={hrefFor} label="Result pages" />

Examples

A gap on both sides

<nav class="cap-pagination" aria-label="Pagination, two gaps" id="pg-both">
  <p class="cap-pagination-status">Showing 141 to 160 of 312 posts</p>
  <ul class="cap-pagination-list">
    <li><a class="cap-page" data-kind="prev" href="#page-7" rel="prev">Previous</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 1" href="#page-1">1</a></li>
    <li class="cap-pagination-num"><span class="cap-page-gap"><span aria-hidden="true">&hellip;</span><span class="cap-sr-only">More pages</span></span></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 7" href="#page-7">7</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 8" aria-current="page" href="#page-8">8</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 9" href="#page-9">9</a></li>
    <li class="cap-pagination-num"><span class="cap-page-gap"><span aria-hidden="true">&hellip;</span><span class="cap-sr-only">More pages</span></span></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 16" href="#page-16">16</a></li>
    <li class="cap-pagination-where">Page 8 of 16</li>
    <li><a class="cap-page" data-kind="next" href="#page-9" rel="next">Next</a></li>
  </ul>
</nav>

The first page: Previous is disabled, still readable

<nav class="cap-pagination" aria-label="Pagination, first page" id="pg-first">
  <p class="cap-pagination-status">Showing 1 to 20 of 312 posts</p>
  <ul class="cap-pagination-list">
    <li><a class="cap-page" data-kind="prev" role="link" aria-disabled="true">Previous</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 1" aria-current="page" href="#page-1">1</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 2" href="#page-2">2</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 3" href="#page-3">3</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 4" href="#page-4">4</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 5" href="#page-5">5</a></li>
    <li class="cap-pagination-num"><span class="cap-page-gap"><span aria-hidden="true">&hellip;</span><span class="cap-sr-only">More pages</span></span></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 16" href="#page-16">16</a></li>
    <li class="cap-pagination-where">Page 1 of 16</li>
    <li><a class="cap-page" data-kind="next" href="#page-2" rel="next">Next</a></li>
  </ul>
</nav>

The last page, a short one: Next is disabled

<nav class="cap-pagination" aria-label="Pagination, last page" id="pg-last">
  <p class="cap-pagination-status">Showing 301 to 312 of 312 posts</p>
  <ul class="cap-pagination-list">
    <li><a class="cap-page" data-kind="prev" href="#page-15" rel="prev">Previous</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 1" href="#page-1">1</a></li>
    <li class="cap-pagination-num"><span class="cap-page-gap"><span aria-hidden="true">&hellip;</span><span class="cap-sr-only">More pages</span></span></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 12" href="#page-12">12</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 13" href="#page-13">13</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 14" href="#page-14">14</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 15" href="#page-15">15</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 16" aria-current="page" href="#page-16">16</a></li>
    <li class="cap-pagination-where">Page 16 of 16</li>
    <li><a class="cap-page" data-kind="next" role="link" aria-disabled="true">Next</a></li>
  </ul>
</nav>

Few pages: every number, no gap

<nav class="cap-pagination" aria-label="Pagination, mentions" id="pg-few">
  <p class="cap-pagination-status">Showing 26 to 50 of 61 mentions</p>
  <ul class="cap-pagination-list">
    <li><a class="cap-page" data-kind="prev" href="#page-1" rel="prev">Previous</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 1" href="#page-1">1</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 2" aria-current="page" href="#page-2">2</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 3" href="#page-3">3</a></li>
    <li class="cap-pagination-where">Page 2 of 3</li>
    <li><a class="cap-page" data-kind="next" href="#page-3" rel="next">Next</a></li>
  </ul>
</nav>

Other words for the ends: Newer and Older, no count line

<nav class="cap-pagination" aria-label="Pagination, newer and older" id="pg-words">
  <ul class="cap-pagination-list">
    <li><a class="cap-page" data-kind="prev" href="#page-2" rel="prev">Newer</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 1" href="#page-1">1</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 2" href="#page-2">2</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 3" aria-current="page" href="#page-3">3</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 4" href="#page-4">4</a></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 5" href="#page-5">5</a></li>
    <li class="cap-pagination-num"><span class="cap-page-gap"><span aria-hidden="true">&hellip;</span><span class="cap-sr-only">More pages</span></span></li>
    <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 16" href="#page-16">16</a></li>
    <li class="cap-pagination-where">Page 3 of 16</li>
    <li><a class="cap-page" data-kind="next" href="#page-4" rel="next">Older</a></li>
  </ul>
</nav>

Buttons, client-side: choosing a page redraws the list and updates the line

<nav class="cap-pagination" aria-label="Pagination, client-side" id="pg-buttons" data-cap="pagination" data-page="1" data-page-count="16" data-total="312" data-per-page="20" data-noun="posts">
  <p class="cap-pagination-status" role="status">Showing 1 to 20 of 312 posts</p>
  <ul class="cap-pagination-list">
    <li><button type="button" class="cap-page" data-kind="prev" aria-disabled="true">Previous</button></li>
    <li class="cap-pagination-num"><button type="button" class="cap-page" aria-label="Page 1" aria-current="page" data-page="1">1</button></li>
    <li class="cap-pagination-num"><button type="button" class="cap-page" aria-label="Page 2" data-page="2">2</button></li>
    <li class="cap-pagination-num"><button type="button" class="cap-page" aria-label="Page 3" data-page="3">3</button></li>
    <li class="cap-pagination-num"><button type="button" class="cap-page" aria-label="Page 4" data-page="4">4</button></li>
    <li class="cap-pagination-num"><button type="button" class="cap-page" aria-label="Page 5" data-page="5">5</button></li>
    <li class="cap-pagination-num"><span class="cap-page-gap"><span aria-hidden="true">&hellip;</span><span class="cap-sr-only">More pages</span></span></li>
    <li class="cap-pagination-num"><button type="button" class="cap-page" aria-label="Page 16" data-page="16">16</button></li>
    <li class="cap-pagination-where">Page 1 of 16</li>
    <li><button type="button" class="cap-page" data-kind="next" data-page="2">Next</button></li>
  </ul>
</nav>

A narrow space: the numbers give way to “Page 3 of 16”

<div class="pagination-narrow-box">
  <nav class="cap-pagination" aria-label="Pagination, narrow" id="pg-narrow">
    <p class="cap-pagination-status">Showing 41 to 60 of 312 posts</p>
    <ul class="cap-pagination-list">
      <li><a class="cap-page" data-kind="prev" href="#page-2" rel="prev">Previous</a></li>
      <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 1" href="#page-1">1</a></li>
      <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 2" href="#page-2">2</a></li>
      <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 3" aria-current="page" href="#page-3">3</a></li>
      <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 4" href="#page-4">4</a></li>
      <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 5" href="#page-5">5</a></li>
      <li class="cap-pagination-num"><span class="cap-page-gap"><span aria-hidden="true">&hellip;</span><span class="cap-sr-only">More pages</span></span></li>
      <li class="cap-pagination-num"><a class="cap-page" aria-label="Page 16" href="#page-16">16</a></li>
      <li class="cap-pagination-where">Page 3 of 16</li>
      <li><a class="cap-page" data-kind="next" href="#page-4" rel="next">Next</a></li>
    </ul>
  </nav>
</div>

Steps form: a journal, newest first, and results whose total moves

<nav class="cap-pagination" aria-label="Journal pages" data-form="steps" id="pg-steps">
  <ul class="cap-pagination-list">
    <li><a class="cap-page" data-kind="prev" href="?page=2" rel="prev">Newer</a></li>
    <li class="cap-pagination-where">Page 3 of 9</li>
    <li><a class="cap-page" data-kind="next" href="?page=4" rel="next">Older</a></li>
  </ul>
</nav>
<nav class="cap-pagination" aria-label="Result pages" data-form="steps" id="pg-steps-open">
  <ul class="cap-pagination-list">
    <li><a class="cap-page" data-kind="prev" role="link" aria-disabled="true">Previous</a></li>
    <li class="cap-pagination-where">Page 1</li>
    <li><a class="cap-page" data-kind="next" href="?q=dickens&amp;page=2" rel="next">Next</a></li>
  </ul>
</nav>

API reference

Pagination

PropTypeRequiredDoes
pagenumberYes
pageCountnumberYes
hrefFor(page: number) => stringLinks (server-rendered): the address of a page. Without it the pager is buttons and onPageChange says which page was chosen.
onPageChange(page: number) => void
totalnumberWith both, the "Showing 21 to 40 of 312 posts" line is shown.
perPagenumber
nounstringWhat the items are, in the plural: "posts".
prevLabelstringNewer and Older for a newest-first list.
nextLabelstring
labelstring
renderLink(props: PageLinkProps) => ReactNodeThe links form through the app's router link, so a page change is a client navigation.
form"numbers" | "steps""steps": Previous and Next with "Page 3 of 16" between at every width, no numbers (a journal read newest first). With a total that moves, pass pageCount 0 and hasNext, and it reads "Page 3".
hasNextboolean

Functions

FunctionSignatureDoes
pageItems(page: number, count: number): PageItem[]The numbers to show for page of count: always seven slots when there are more than seven pages, so the list never changes width as a person moves. The first and last page are always there; a gap stands for the pages between.
showingRange(page: number, perPage: number, total: number): { from: number; to: number; }The first and last item on page, counted from 1.
statusText(page: number, perPage: number, total: number, noun?: string): string"Showing 21 to 40 of 312 posts". A page with one item says "Showing 41 of 41 posts".
pageCountOf(total: number, perPage: number): number
parsePage(raw: string | null | undefined): numberThe page an address asks for: ?page= read strictly. Only whole digits count ("2", not "2.5", "-1", "1e3" or "2abc"), and only a safe integer from 1; anything else is page 1. A loader then keeps it inside the list with pageEnvelope (a page past the end shows the last page).
pageEnvelope(page: number, perPage: number | "all", total: number): PageEnvelopeEverything a list page needs from its total: the page kept in range, the offset to query, the range shown and whether there is a way back or on. perPage "all" shows the whole list on one page.
pageHref(path: string, params: URLSearchParams | Record<string, string | number | boolean | null | undefined>, page: number, options?: { param?: string | undefined; }): stringThe address of one page of a list: the path, the list's other parameters with their empty or default values left out, and page only past the first (page 1 is the bare address, so one page has one address). Parameter order is kept, so the same list always has the same address.
pageRelLinks(page: number, pageCount: number, hrefFor: (page: number) => string): { rel: "next" | "prev"; href: string; }[]The pages before and after this one, for <link rel="prev"> and <link rel="next"> in the head (a route's links export), so crawlers and readers that follow them find the series.
render(nav: HTMLElement): voidDraws the nav's list and status from its data attributes: the markup in pagination.md, with buttons for links.
setPage(nav: HTMLElement, page: number, options?: { silent?: boolean | undefined; }): booleanGoes to a page from script. Draws again, keeps focus on the control that had it (or on the current page when that control is gone), and tells the page. Returns whether the page changed.
enhance(root?: ParentNode): () => voidAttaches every [data-cap="pagination"] under root not yet attached. Returns a function that detaches them.

CSS variables

VariableDefault
--pagination-gapvar(--space-7)

Parts and data attributes

ClassIs
.cap-pageits own class
.cap-page-gapits own class
.cap-paginationthe root
.cap-pagination-lista part
.cap-pagination-numa part
.cap-pagination-statusa part
.cap-pagination-wherea part
AttributeValues
data-formsteps
data-kindnext prev
StateRead from
:activethe platform
:focus-visiblethe platform
:hoverthe platform
:visitedthe platform
[aria-current="page"]an attribute
[aria-disabled="true"]an attribute

Accessibility

KeyDoes
Tab, Shift+TabMoves through Previous, the page numbers and Next. A disabled link is not a stop; a disabled button is
EnterFollows the focused link, or chooses the focused page (buttons)
SpaceChooses the focused page (buttons)

In the buttons form, focus stays on the control that was used: after Next it is on Next while there are more pages, otherwise on the current page.

  • A nav named "Pagination"; give each pager on a page its own name ("Posts pages", "Mentions pages").
  • Page links have aria-label="Page n"; the current one aria-current="page". The gap is "More pages" to a reader and … to the eye.
  • A disabled end: aria-disabled="true"; its text keeps 4.5:1.
  • Contrast: link text 4.5:1; the current page's edge, Previous's and Next's edges 3:1.
  • Hit areas at least var(--control) square; forced colors draw the current page in Highlight.