Build Assets
UI Component
Pagination
Navigation control for moving through paged content sets.
Platform: bothTags: pagination, navigation, pages, table, list
Purpose
Divides large content sets into discrete pages. Use when: total count is known, random access by page number is useful, and the full set is too large to render at once. For unknown-length feeds, use infinite scroll instead.
Anatomy
- Previous button: ← left arrow, disabled on page 1
- Page numbers: current highlighted, 2 on each side, ellipsis for gaps
- Next button: → right arrow, disabled on last page
- Optional: items-per-page selector (25 / 50 / 100)
- Optional: page count label "Page 3 of 24"
States
- Current page: filled accent background, not clickable
- Adjacent pages: text only, hover background
- Prev/Next disabled: 40% opacity, not clickable
- Loading: current page button shows spinner
Tokens
spacing
buttonSize: 36pxbuttonGap: 4pxborderRadius: 6px
Do
- Show current position: "Page 3 of 24" or total results count
- Maintain page state in the URL (?page=3) for shareability and back-button
- Show 2 page numbers on each side of current: … 1 2 [3] 4 5 … 24
- Minimum button size 36×36px (touch target consideration)
Don't
- Use pagination for infinite-scroll content where page structure is meaningless
- Show all page numbers when count > 10 — use ellipsis
- Reset to page 1 on filter/sort change without user intent
- Disable the entire UI while paginating — show loading inline
Accessibility
- nav element with aria-label="Pagination"
- aria-current="page" on the active page button
- aria-disabled="true" on disabled prev/next
- Page numbers announce context: "Page 3 of 24"