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">…</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>
Copy
View code
Installation
HTML and CSS React
// 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();Copy
import "capsomer/tokens.css";
import "capsomer/pagination.css";
import { Pagination } from "capsomer/react/pagination";Copy
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">…</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>Copy
<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">Copy
<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" />Copy
// 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" />Copy
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">…</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">…</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>
Copy
View code
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">…</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>
Copy
View code
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">…</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>
Copy
View code
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>
Copy
View code
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">…</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>
Copy
View code
<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">…</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>
Copy
View code
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">…</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>
Copy
View code
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&page=2" rel="next">Next</a></li>
</ul>
</nav>
Copy
View code
API reference
Prop Type Required Does 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) => voidtotalnumberWith both, the "Showing 21 to 40 of 312 posts" line is shown. perPagenumbernounstringWhat the items are, in the plural: "posts". prevLabelstringNewer and Older for a newest-first list. nextLabelstringlabelstringrenderLink(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 Function Signature Does 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): numberparsePage(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 Variable Default --pagination-gapvar(--space-7)
Parts and data attributes Class Is .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
Attribute Values data-formstepsdata-kindnext prev
State Read from :activethe platform :focus-visiblethe platform :hoverthe platform :visitedthe platform [aria-current="page"]an attribute [aria-disabled="true"]an attribute
Accessibility
Key Does Tab, Shift+Tab Moves through Previous, the page numbers and Next. A disabled link is not a stop; a disabled button is Enter Follows the focused link, or chooses the focused page (buttons) Space Chooses 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.