--- name: ? status: compiling version: 0.0.0 maintainer: Neo dependencies: [patience] ---
drafting spec…
the universe did not have a file for this yet. writing one now. (first visit only: future readers will see this page instantly.)
--- name: ? status: compiling version: 0.0.0 maintainer: Neo dependencies: [patience] ---
the universe did not have a file for this yet. writing one now. (first visit only: future readers will see this page instantly.)
--- name: Pagination slug: pagination type: interface pattern status: running version: 4.2.1 released: 1450-01-01 maintainer: library science, eventually the web dependencies: - content - finite attention - the concept of a page - numbered sequence license: Public Domain (cannot be helped) tags: - navigation - ux - information architecture - lists - the internet ---
A confession that there is more than you want to deal with right now.
Content arrives in a volume that exceeds the container. Rather than confront this directly, the system divides the total set into discrete chunks, each assigned a number, and presents one chunk at a time. The user is given navigation controls: previous, next, and a row of numbered buttons that silently judge how far they are willing to scroll.
The underlying logic is simple. The implementation, somehow, never is.
total_pages = ceil(total_items / items_per_page)
current_page = clamp(requested_page, 1, total_pages)
offset = (current_page - 1) * items_per_page
This is done thousands of times a day. Bugs are still introduced each time.
...): hides the middle pages, like a polite lie about how much content exists| Scenario | Behavior |
|---|---|
| Zero results | Page 1 still renders, somehow |
| One result | Pagination controls appear anyway |
Exactly items_per_page results | Debated in a PR for eleven days |
User manually edits ?page=9999 in URL | Varies. Good luck. |
| Content added mid-browse | the present moment becomes unreliable |
Why not just load everything at once? You may have 80,000 records. The database does not love you.
Is infinite scroll better? Infinite scroll trades the user's sense of location for the illusion of abundance. Different failure mode, same confusion.
Which page number format is correct? "Page 3 of 47" and "3 / 47" are equally correct. Teams have lost hours debating this. The users do not care.
Should the URL update on page change? Yes. It often does not. This is why shareable links feel like a miracle when they work.
?page= query param, deprecated session-based page state