Components
Pagination
Pagination
Page-numbered nav for deep-linkable lists. The complement of <koala-load-more> — use load-more for infinite-scroll feeds, pagination for lists where the URL should reflect the current page (shareable invoice / report views).
Canonical (page 1 of 10)
Middle of a long list (page 7 of 24)
Ellipses appear when there's a gap between first / current-window / last. Adjust the window with neighbours.
Last page (page 10 of 10)
The next-arrow is disabled (no link, low contrast). Same on the prev-arrow for page 1.
Wider window (neighbours=2)
Pages within ±N of the current page are always shown. Default neighbours=1.
Single page (suppressed)
(Nothing renders when there's only one page.)
Props
| Attribute | Values | Notes |
|---|---|---|
| current-page | int (1-indexed) | Required. Clamped to [1, total-pages]. |
| total-pages | int | Required. Suppresses the nav entirely when ≤ 1. |
| page-url-template | String containing {page} | Required. The literal {page} token is replaced per page. |
| neighbours | int | Default 1. Pages within ±N of current are always rendered. |
| class | Tailwind classes | Merged with the nav's base classes. |
Do & don't
page-url-template="/quotes?page={0}"preserves the existing query string
Do
Use a URL template that keeps existing query params (filters, sort). Pagination should never drop user state.
Prev / Next only, no page numbers
Don't
Don't ship prev/next without numbers when the list could span more than 5 pages. Users need to skip directly — numbered links carry the user's mental map.