Every page, Previous and Next target is a real link, so pages can be opened in a new tab, crawled and shared. page is owned by your application: Pagination never keeps its own page state, it only renders the window around the page you give it, keeping the first and last pages and collapsing the rest into ellipses.
Client-side routing
By default each link points at the current URL with its page query parameter replaced. A client router listens for tp-value-change, prevents the original click and sets page itself; modifier-key clicks keep native link behavior.
Canceling the proposal prevents navigation. Activating the current page does not reload the same destination.
Router handling
Default density
Compact density
Restart from the initial state
Show the copyable source
Hide parts through their properties: showPageLinks = false leaves only the directions, and showLabels = false keeps the arrows with their accessible names. These default to true, so set them in JavaScript; an attribute set to "false" still counts as present.
Below a 40rem width, Previous and Next retain their accessible names and icons while their visible labels are hidden. Resizing does not replace links or reset the current page.
Directions only
Default density
Compact density
Restart from the initial state
Show the copyable source
Disable Pagination while a page is loading so people cannot queue up navigations; the links keep their place in the layout.
API Reference
Every element also accepts motion-policy.
Attributes
AttributePropertyTypeDefaultDescriptionpagepagenumber1The application's current page, a positive integer; update it after accepting a proposal.pagespagesnumber1Total number of pages, a positive integer.labellabelstring'Pagination'Accessible name of the navigation landmark.page-link-variantpageLinkVariant'text' | 'icon''icon'text sizes numbered links to their content, for large page numbers; icon keeps them square.previous-labelpreviousLabelstring'Previous'Visible and accessible name of the previous link, for localization.next-labelnextLabelstring'Next'Visible and accessible name of the next link, for localization.show-previousshowPreviousbooleantrueWhether the previous link renders; set it to false from script to leave only numbered links.show-nextshowNextbooleantrueWhether the next link renders; set it to false from script to leave only numbered links.show-page-linksshowPageLinksbooleantrueWhether numbered links and omitted ranges render; false leaves only the directions.show-labelsshowLabelsbooleantrueWhether the directions show their text; false keeps named arrows at every width.
Properties
PropertyTypeDefaultDescriptionhrefForPage((page: number) => string) | undefined—Destination of each page's link, for path-based routes; by default the current URL with its page query parameter replaced.pageLabel((page: number) => string) | undefined—Accessible name of each numbered link, for localization; by default "Page" and the locale-formatted number.onPageChange((event: TpValueChangeEvent<number>) => void) | undefined—Called with the same cancelable proposal as tp-value-change, before it is dispatched.
Events
EventTypeDescriptiontp-value-changeTpValueChangeEvent<number>Cancelable proposal of the page a link leads to; detail.value is the page and detail.sourceEvent the click, whose default a client router prevents. Not dispatched for modified clicks, which keep native link behavior.
CSS parts
PartDescription::part(pagination)The navigation landmark around the links.::part(pagination-ellipsis)The mark for an omitted range of pages, hidden from assistive technology.::part(pagination-list)The list of links.::part(pagination-next)The link to the next page.::part(pagination-page-item)The list item around each link or omitted range.::part(pagination-page-link)A numbered page link; the current page is marked aria-current="page".::part(pagination-previous)The link to the previous page.