---
name: pagination
slug: pagination
type: ui_pattern / existential_condition
status: unstable
version: 0.0.666-alpha
released: "whenever someone decided infinity was too much"
maintainer: the_ghost_in_the_grid
dependencies:
  - content
  - arbitrary_limits
  - user_patience
  - the_number_ten
  - [cognitive_load](/cognitiveload)
license: MIT (but something feels wrong about it)
tags:
  - navigation
  - illusion_of_control
  - chunks
  - where_did_page_4_go
  - haunted_ux
---

pagination

What it actually is

A negotiation between infinite content and finite attention, resolved by drawing lines where no lines naturally exist.

How it works

Content arrives. Content is too much. Someone, somewhere, decides the correct unit of experience is "page." Nobody agrees on what a page is. The decision ships anyway.

Total items are counted (or estimated, or lied about)
A chunk size is selected, usually 10, 20, or 25, for reasons no one can trace to a meeting
Items are sliced at the chunk boundary, mid-thought if necessary
Navigation controls are rendered: prev, next, and a row of numbers that judge you
User clicks to page 7
Page 7 is empty
This is considered acceptable

"I just wanted to see all the results." — every user, forever

Features

Numbered pages: creates the sensation of location inside content. Sensation only.
Prev / Next controls: binary, confident, wrong about what you wanted
Current page indicator: tells you where you are. Not where the thing you need is.
Total count display: "1,847 results." Meaningless. Comforting. Both.
Ellipsis (...): the spec acknowledges it cannot fully render itself here either

WARNING: Ellipsis hides pages. Those pages do not know they are hidden. They wait.

Error codes

ERR_PAGE_NOT_FOUND         : requested page exceeds total. total was a guess.
ERR_CURSOR_DRIFT           : cursor-based pagination returned a different page 2 than yesterday
ERR_ZERO_INDEXED_SHAME     : page 0 exists. no one is ready for this.
ERR_CHUNK_ORPHAN           : last page has 1 item. it knows.
ERR_INFINITE_SCROLL_NEARBY : pagination detects competition and becomes unstable
ERR_666                    : you are on every page simultaneously. close the browser.

Known bugs

Sorting by a different column resets to page 1, invalidating the user's memory of where they were
"Page 3 of 3" sometimes becomes "Page 3 of 4" between requests. The fourth page contains 0 results and a mild dread
Deep linking to page 47 causes imposter syndrome in the page itself
Removing one item from page 2 shifts all subsequent pages forward. The content does not consent to this.
Mobile implementations frequently omit numbered pages and offer only Prev/Next, which is technically pagination the same way rationing is technically a meal

Edge cases

The spec was going to document these but then something

Configuration

page_size: 10          # or 20. or 25. consult a fortune teller.
show_total: true       # whether to display the count or protect the user
first_page_index: 1    # (0 in some traditions. those traditions are haunted.)
ellipsis_threshold: 7  # pages before the ... appears and swallows the middle
scroll_to_top_on_page_change: debated

FAQ

Q: Should I use pagination or infinite scroll? A: Yes.

Q: What is the correct page size? A: The one that was already decided before you joined the team.

Q: Why does page 1 load fast and page 8 take four seconds? A: Page 8 has been waiting longer.

Q: Is offset-based pagination bad? A: It is legacy. It is also what you have. Welcome.

drafting spec…