Pagination

Pagination in three forms: numbered pages, page dots that stretch as you swipe, and a Show more button that shows loading dots and marks the end of the list.

Preview

Installation

npx @lumioui/cli add pagination

Usage

import { PageDots, LoadMore, Pagination } from "@/components/ui/pagination/pagination";
<Pagination />

Also exported: PageDots, LoadMore.

Examples

Dots

Swipe between cards in a banking wallet.

Load more

Reviews under a recipe.

Numbers

A helpdesk inbox paged five tickets at a time.

API reference

Pagination

Prop Type Default
total* number

Total number of pages.

—
page number

Controlled current page (1-based).

—
defaultPage number

Uncontrolled initial page (1-based). Default 1.

—
onPageChange (page: number) => void

Fires with the new page when a number or arrow is tapped.

—
siblings number

Pages shown either side of the current one. Default 1.

—
boundaries number

Pages always shown at each end. Default 1.

—
variant "numbers" | "compact"

"numbers" — ‹ 1 … 4 5 6 … 12 › with a current-page disc that switches on in place. "compact" — ‹ Page 5 of 12 › for narrow rows and table footers.

—
hideArrows boolean

Hide the previous / next arrows. Default false.

—
disabled boolean

Disable every control.

—
haptic boolean

Haptic on page change. Default true.

—
className string —

PageDots

Prop Type Default
count* number

Number of pages.

—
index number

Current page (0-based). Used when progress isn't supplied.

0
progress SharedValue<number>

Continuous page position (0 … count-1) on the UI thread — e.g. scrollX / pageWidth from useAnimatedScrollHandler. The dots morph with the finger instead of snapping when the page settles.

—
onIndexChange (index: number) => void

Tap left / right of the active dot to step a page (page-control style).

—
variant "pill" | "dot"

"pill" — active dot stretches into a capsule. "dot" — classic page dots. Default "pill".

"pill"
tone "default" | "inverse"

"default" ink on canvas, "inverse" white for dots over photos/video.

"default"
className string —

LoadMore

Prop Type Default
onLoadMore () => void | Promise<unknown>

Fetch the next page. Return a promise and the footer tracks loading itself.

—
loading boolean

Controlled loading state (otherwise derived from the onLoadMore promise).

—
hasMore boolean

More results exist. When false the footer settles into its end state. Default true.

true
remaining number

Items still to load — "Show 24 more" reads better than "Load more".

—
label string

Button label. Default "Show {remaining} more" or "Load more".

—
endLabel string

End-of-list line. Default "You're all caught up".

"You're all caught up"
variant "button" | "auto"

"button" — a full-width secondary button (feeds, reviews). "auto" — busy-dots-only footer for FlatList onEndReached infinite lists.

"button"
className string —