Pagination
Links to the pages of a long list, with previous and next and a gap for skipped pages.
Pagination splits a long list into pages and links to them. Each page is a link with an href,
so it can be opened in a new tab, shared and bookmarked. It only renders the links: which pages to
show and what a page contains are your application's.
Page 5 of 12
// apps/docs/examples/ui/pagination.tsx'use client';
import {useState, type MouseEvent} from 'react';
import { Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious,} from '@workspace/active-ui/components/primitives/pagination';
const PAGES = 12;
/** The page numbers to show: the first, the last, and the current with its neighbours. */function visiblePages(current: number): (number | 'gap')[] { const pages: (number | 'gap')[] = []; for (let page = 1; page <= PAGES; page++) { if (page === 1 || page === PAGES || Math.abs(page - current) <= 1) { pages.push(page); } else if (pages.at(-1) !== 'gap') { pages.push('gap'); } } return pages;}
/** * Links to the pages of a long list. Each link has a real `href` * (`?page=n`); this example keeps the page in state instead of navigating, * where an application would let the router follow the link. */export default function PaginationExample() { const [page, setPage] = useState(5); const go = (target: number) => (event: MouseEvent<HTMLAnchorElement>) => { event.preventDefault(); setPage(target); }; return ( <div className="flex flex-col items-center gap-3"> <Pagination label="Pages of participants"> <PaginationContent> {page > 1 ? ( <PaginationItem> <PaginationPrevious href={`?page=${page - 1}`} text="Previous" label="Go to the previous page" onClick={go(page - 1)} /> </PaginationItem> ) : null} {visiblePages(page).map((entry, index) => entry === 'gap' ? ( <PaginationItem key={`gap-${index}`}> <PaginationEllipsis /> </PaginationItem> ) : ( <PaginationItem key={entry}> <PaginationLink href={`?page=${entry}`} isActive={entry === page} aria-label={`Page ${entry}`} onClick={go(entry)} > {entry} </PaginationLink> </PaginationItem> ), )} {page < PAGES ? ( <PaginationItem> <PaginationNext href={`?page=${page + 1}`} text="Next" label="Go to the next page" onClick={go(page + 1)} /> </PaginationItem> ) : null} </PaginationContent> </Pagination> <p className="text-muted-foreground text-sm" aria-live="polite"> Page {page} of {PAGES} </p> </div> );}Usage#
import { Pagination, PaginationContent, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious,} from '@workspace/active-ui/components/primitives/pagination';
<Pagination label="Pages of participants"> <PaginationContent> <PaginationItem> <PaginationPrevious href="?page=4" text="Previous" label="Go to the previous page" /> </PaginationItem> <PaginationItem> <PaginationLink href="?page=5" isActive> 5 </PaginationLink> </PaginationItem> <PaginationItem> <PaginationNext href="?page=6" text="Next" label="Go to the next page" /> </PaginationItem> </PaginationContent></Pagination>;Anatomy#
Pagination: the<nav>landmark, named bylabel.Pagination(Content <ul>) with aPagination(Item <li>) per link.Pagination: a link styled as a button.Link ismarks the current page (Active aria-, outlined);current="page" sizeas on Button,iconby default.PaginationandPrevious Pagination: links with an arrow.Next textis the visible text, hidden below thesmwidth;labelis the accessible name.Pagination: the sign for skipped pages, hidden from assistive technology.Ellipsis
What your application provides#
labelof the landmark, andtextandlabelof the previous and next links (required).The
hrefof every link. Without one, an<a>is not focusable.Which pages to show, and leaving out the previous link on the first page and the next link on the last: the links have no disabled state.
With a client-side router: let the router follow the link (
renderwith your router's link, oron), as the example does with state.Click
Accessibility and keyboard#
A
<nav>with a list of links;Tabmoves through them andEnterfollows one.The current page is announced as such. A page number alone is a short name: give the links an
aria-such as "Page 5" when the context does not make it clear.label
API#
Pagination
Props
- Type
string
The name of the navigation landmark, such as "Pages of participants".
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
PaginationLink
Props
- Type
boolean
Whether this link is the current page: outlined, with aria-.
- Type
"default""icon""icon-lg" "icon-sm" "icon-xs" "lg""sm""xs"null- Default
'icon'
The height and padding. xs, sm, default and lg for a button with text; icon-, icon-, icon and icon- for a square button with only an icon, which then needs an accessible name (aria-).
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
PaginationNext
Props
- Type
string
The accessible name of the link, such as "Go to the next page".
- Type
string
The visible text beside the arrow, hidden below the sm width.
- Type
boolean
Whether this link is the current page: outlined, with aria-.
- Type
"default""icon""icon-lg" "icon-sm" "icon-xs" "lg""sm""xs"null
The height and padding. xs, sm, default and lg for a button with text; icon-, icon-, icon and icon- for a square button with only an icon, which then needs an accessible name (aria-).
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
PaginationPrevious
Props
- Type
string
The accessible name of the link, such as "Go to the next page".
- Type
string
The visible text beside the arrow, hidden below the sm width.
- Type
boolean
Whether this link is the current page: outlined, with aria-.
- Type
"default""icon""icon-lg" "icon-sm" "icon-xs" "lg""sm""xs"null
The height and padding. xs, sm, default and lg for a button with text; icon-, icon-, icon and icon- for a square button with only an icon, which then needs an accessible name (aria-).
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
Parts that take only their elementโs attributes
Pagination: the attributes of aContent <ul>, with className and ref.Pagination: the attributes of aEllipsis <span>, with className and ref.Pagination: the attributes of aItem <li>, with className and ref.
This page adapts the Pagination documentation of shadcn/ui (MIT licence) to this package; see Third-party notices.