Pagination

Page numbers with previous and next, from a page count or composed from parts.

Example
import { Pagination } from "@elements/ui/pagination";

<Pagination page={state.page} total={20} />

<Pagination page={current} total={20} href={(p) => `/orders?page=${p}`} />

Parts

Part	What it is
Pagination	The nav landmark. With total it renders the whole control; without, its slot.
PaginationContent	The list of items.
PaginationItem	One list item.
PaginationLink	A page link. active marks the current page.
PaginationPrevious	Link to the previous page: a chevron and text.
PaginationNext	Link to the next page: text and a chevron.
PaginationEllipsis	Marks skipped pages; reads as "More pages".

Attributes

Pagination

Attribute	Type	Default	Description
page	number (two-way)	1	The current page, from startValue (1). Shown within startValue..total when it falls outside, as after total shrinks.
total	number | undefined	undefined	The page count. 0 (no results) keeps Previous and Next, disabled, so the pager holds its place. Omitted renders the slot for a composed pagination.
siblings	number	1	Pages shown either side of the current one.
boundaries	number	1	Pages kept at each end.
href	(page: number) => string	undefined	Renders links with these targets. Without it the pages are buttons.
controls	boolean	true	Show Previous and Next.
numbers	boolean	true	Show page numbers. false shows "Page N of M" between the controls.
edges	boolean	false	Show First and Last.
startValue	number	1	The first page number: pages run from startValue to total.
size	"sm" | "md" | "lg"	"md"	Control size.
variant	"text" | "outlined"	"text"	outlined: a border on every page and control; the current page takes the accent border.
color	"standard" | "primary" | "secondary"	"standard"	primary or secondary fills the current page with that button color.
shape	"rounded" | "circular"	"rounded"	circular: round pages and controls.
layout	"default" | "responsive"	"default"	responsive: in a narrow container, Page X of Y (statusText) replaces the page numbers.
label	string	"Pagination"	aria-label of the nav.
previousText	string	"Previous"	Previous control text.
nextText	string	"Next"	Next control text.
getItemLabel	(kind: "first" | "previous" | "next" | "last" | "page", page: number) => string	undefined	The aria-label of each control and page, for translation. page is the page the item goes to. Without it, English labels; translated control text with no label is the control's name.
statusText	(page: number, total: number) => string	Page N of M	The status between the controls when numbers is false, for translation.
disabled	boolean	false	Turns off every page and control: aria-disabled, no href, presses ignored.
hideWithOnePage	boolean	false	Renders nothing when total is 1, so a one-page list shows no pager.
onPageChange	(page: number) => void	() => {}	Called when the user changes the page. Not called for changes the caller makes.
class	string	""	Extra classes. Every part takes class.

PaginationLink

Attribute	Type	Default	Description
href	string	""	The page's URL. Also on PaginationPrevious and PaginationNext.
active	boolean	false	The current page: outline look, aria-current="page".
size	"sm" | "md" | "icon"	"icon"	icon is a square for a number; md and sm fit text.
disabled	boolean	false	No href, aria-disabled, clicks ignored. Also on PaginationPrevious and PaginationNext.
attrs	Record<string, string | number | boolean | undefined>	{}	Other attributes for the anchor. Also on PaginationPrevious and PaginationNext.
onclick	(e: MouseEvent) => void	() => {}	Click handler. Also on PaginationPrevious and PaginationNext.

PaginationPrevious

Attribute	Type	Default	Description
text	string	"Previous" / "Next"	The control text, for translation. Also on PaginationNext.
label	string	""	The aria-label. Empty: "Go to previous page" for the English text, or the text itself once it is translated. Also on PaginationNext.

Slots

Slot	Part	Content
default	Pagination	A PaginationContent, when total is 0.
first-icon	Pagination	An Icon that replaces First's chevrons. Also previous-icon, next-icon and last-icon.
dots-icon	Pagination	An Icon that replaces the ellipsis in every gap.
default	PaginationContent	PaginationItems.
default	PaginationLink	The page number.

Keyboard

Keys	Action
Tab	Moves through the controls and pages.
Enter	Follows a link or presses a button.
Space	Presses a button.

Data attributes

Attribute	Values	On
data-active	present on the current page	page link
data-disabled	present at the ends, or on everything when disabled	controls
data-disabled	present when disabled	Pagination

Accessibility

• A nav landmark labelled Pagination around a list.
• The current page has aria-current="page"; each page button is labelled "Page N".
• Previous, Next, First and Last are labelled ("Go to next page"); at the ends they are aria-disabled and keep focus instead of dropping it.
• Translated control text with no label becomes the control's name, so what is read matches what is shown; getItemLabel translates every label.
• Ellipses are hidden from assistive tech; the composed part says "More pages".

See also

• Accordion (opens in a new tab): A stack of headings that each show and hide a panel, one or several at a time.
• Collapsible (opens in a new tab): A trigger that shows and hides a region, with its height animated.
• Tabs (opens in a new tab): Layered panels, one shown at a time, chosen from a list of tabs.
• Breadcrumb (opens in a new tab): The path to the current page as a trail of links, composed from parts or built from a list.
• Tree (opens in a new tab): A hierarchical list that opens with the arrow keys, selects one node or many, and loads children on demand.