Pagination

Page navigation as real links. CSS only. CSS only

Choosing between components

This paginates pages — one URL each. To page through the options inside a Listbox, Select, or Combobox, set page-size on that element and author its pager parts instead; nothing navigates there, so links would be wrong.

Markup you author

Give the <nav> an aria-label. Author every page but the current one as an <a href>, the current one as a <span aria-current="page">, and the ellipsis as aria-hidden="true". Previous and Next need accessible names that say what they do, and at the first or last page they become <span> elements — an <a aria-disabled="true"> still navigates, so it is a lie. Compose <ul class="ui-group" data-ui-attached> for a joined strip.

Pagination

Copy this markup

<nav class="ui-pagination" aria-label="Pagination">
  <ul>
    <li data-ui-part="item"><a data-ui-part="previous" href="?page=3" rel="prev">Previous</a></li>
    <li data-ui-part="item"><a data-ui-part="link" href="?page=1" aria-label="Page 1">1</a></li>
    <li data-ui-part="item"><span data-ui-part="ellipsis" aria-hidden="true">&hellip;</span></li>
    <li data-ui-part="item"><a data-ui-part="link" href="?page=3" aria-label="Page 3">3</a></li>
    <li data-ui-part="item"><span data-ui-part="link" aria-current="page">4</span></li>
    <li data-ui-part="item"><a data-ui-part="link" href="?page=5" aria-label="Page 5">5</a></li>
    <li data-ui-part="item"><span data-ui-part="ellipsis" aria-hidden="true">&hellip;</span></li>
    <li data-ui-part="item"><a data-ui-part="link" href="?page=12" aria-label="Page 12">12</a></li>
    <li data-ui-part="item"><a data-ui-part="next" href="?page=5" rel="next">Next</a></li>
  </ul>
</nav>

Install

Styles and registration

import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/pagination.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/pagination.css'

Anatomy

Parts are authored in your own markup and identified by the selector below, so your CSS can target the same anatomy without loading Timeless styles. Required parts must be present for the component to work. Private data-ui-internal-* hooks are written by the runtime and must never be authored.

Part	Required	Selector	Purpose
item	No	[data-ui-part~='item']	One cell wrapper. Use <li>.
link	No	[data-ui-part~='link']	A page cell. Use <a href> for every page but the one you are on, and a <span aria-current="page"> for that one.
previous	No	[data-ui-part~='previous']	Steps back one page. Give it an accessible name that says so; ‹ alone names nothing. At the first page, render it as a <span> rather than a disabled link.
next	No	[data-ui-part~='next']	Steps forward one page, with the same two rules.
ellipsis	No	[data-ui-part~='ellipsis']	Stands for the pages omitted from a long range. Mark it aria-hidden="true": the gap between page 3 and page 40 is not a page.

Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes are presence-based: author the attribute with no value, or omit it.

Attribute	Values	Default	Description
data-ui-size	sm · md · lg	md	Cell height, padding, and font size.

State

Native attributes, ARIA, and platform pseudo-classes are authoritative. Style state through the selectors below rather than adding your own state classes.

State	Source	How to express it
current	aria	Author aria-current="page" on the cell for the page being shown. Timeless never writes it.

Styling

Root identity: ui-pagination. Required stylesheets: tokens.css, core/pagination.css, themes/atmosphere/tokens.css, themes/atmosphere/pagination.css.

Set these custom properties to restyle the component:

Custom property	Controls
--ui-pagination-gap	Gap between cells.
--ui-pagination-cell-size	Minimum height and width of a cell.

Design tokens this component reads (17)

These are global Atmosphere tokens. Change them once at the theme level rather than per component.

--ui-accent · --ui-bg-accent · --ui-bg-control-active · --ui-bg-control-hover · --ui-bg-surface · --ui-duration-fast · --ui-ease-standard · --ui-fg · --ui-fg-muted · --ui-fg-subtle · --ui-focus · --ui-line · --ui-radius-control · --ui-shadow-control-active · --ui-shadow-outline-control · --ui-space-1 · --ui-space-3

Accessibility

Keep the native elements, roles, and relationships shown in the example. Timeless adds only the state and keyboard coordination the platform does not already provide, and it never supplies your accessible names — those depend on your content.

The ARIA Authoring Practices Guide has no pattern for Pagination. The contract below is a composition of behavior the platform already defines, not ARIA invented to fill the gap.

The APG has no pagination pattern, so this documents a composition: a <nav> with an aria-label, a list, and one link per page. They are links rather than buttons on purpose — a page is a URL, so it is shareable, middle-clickable, and in the back button’s history, none of which a click handler gives you. That has one consequence worth stating: a disabled link is not a thing. At the first or last page, render Previous or Next as a <span>, not an <a aria-disabled="true"> that still navigates. Compose <ul class="ui-group" data-ui-attached> for a joined strip.

Before JavaScript runs

This primitive is CSS only. There is nothing to register and nothing to wait for.

More examples

Open Pagination in StoryLite for variants, controls, and manual testing.