Components · Navigation
Pagination
Moves through a paged result set and controls how many rows appear at a time. Sits beneath a table, in the table footer.
Figma source: Pagination ↗Examples
Pagination — the page numbers are live
<nav class="cds-pagination" aria-label="Pagination">
<ul class="cds-pagination__list">
<li><button class="cds-pagination__item" aria-label="Previous page" disabled>‹</button></li>
<li><button class="cds-pagination__item" aria-current="page">1</button></li>
<li><button class="cds-pagination__item">2</button></li>
<li><span class="cds-pagination__ellipsis" aria-hidden="true">…</span></li>
<li><button class="cds-pagination__item">18</button></li>
<li><button class="cds-pagination__item" aria-label="Next page">›</button></li>
</ul>
</nav>Figma properties
| Property | Values | Notes |
|---|---|---|
Page Numbers → State | Selected Page · Unselected Page · More/Less Indicator | The ellipsis is modelled as a page-number variant. |
Arrow Buttons → State | On (More) · Disabled (No more) | Disabled at the ends. |
Per Page Dropdown → Number | text | Rows per page. |
The Figma annotations define the truncation rule precisely:
- The More/Less indicator is not clickable. It signals that more pages exist than current page + 3.
- When shown, it sits immediately before the total page count.
- If the second listed page would exceed current page + 3, it becomes the indicator instead of a number.
Usage
When to use it
- Show the current range and the total — “1–25 of 442”. It is the fastest way to answer “how much is there?”.
- Disable rather than hide the arrows at the ends, so the control does not change width.
- Keep the rows-per-page choice next to the pager.
- Return the user to the top of the table after a page change.
When not to use it
- Do not use for sequential steps — that is Previous/Next.
- Do not make the ellipsis clickable; it means “there are more”, not “jump here”.
- Do not reset filters or sorting when the page changes.
- Do not paginate a list short enough to show in full.
Accessibility
- Wrap in
<nav aria-label="Pagination">. - Mark the current page with
aria-current="page". - Arrow buttons need text names — “Previous page”, “Next page”. The glyph alone is not a name.
- The ellipsis is
aria-hidden="true"; it conveys nothing useful when spoken. - Announce the new range after a page change through a polite live region, so a screen-reader user knows the table content was replaced.
Tokens consumed
| Token | Applied to | Resolves to |
|---|---|---|
--pagination-selected-background | Current page fill | --primary-brand-color |
--pagination-selected-text | Current page label | --color-white |
--pagination-default-background | Other pages | --color-white |
--pagination-border | Item borders | --color-gray-300 |
--pagination-disabled | Disabled arrows | --color-gray-300 |