iconiq
—Open GitHub

Pagination

Animated pagination control with compact numbering, previous and next affordances, and a centered page rail that stays steady as the active range shifts.

Open in

Installation

npx shadcn@latest add @iconiq/pagination

Props

Pagination

4 props

Pagination root that can either render the full paginator from total, page, and onChange props or act as the parent wrapper for the composed shadcn-style pieces.
totalnumber
Total number of pages available. When you use the built-in wrapper mode, the component renders the first page, last page, current page, and one sibling on either side, collapsing the rest into ellipsis markers.
pagenumber
Controlled current page. When omitted, the root manages its own page state internally starting from page 1.
onChange(page: number) => void
Called whenever a valid next page is chosen from the numbered buttons or the previous and next controls. The composed primitives also use this through context when you do not provide custom button handlers.
childrenReactNode
Optional composed pagination structure. When omitted, the root renders the full paginator automatically using total, page, and onChange.

Notes

This keeps the same UI and motion treatment as the original single-component paginator, but now also exposes shadcn-style building blocks.
Out-of-range page changes are ignored, so previous is inert on page 1 and next is inert on the final page.

PaginationContent and PaginationItem

1 prop

The composed content wrapper keeps previous and next controls on the edges while the page links stay centered inside the same fixed-width rail.
childrenReactNode
Required
Render PaginationPrevious, PaginationNext, PaginationLink, and PaginationEllipsis inside PaginationContent. Numeric and ellipsis entries can be wrapped with PaginationItem.

Notes

PaginationContent preserves the same centered 280px page rail from the current design instead of switching to a looser layout.
PaginationItem uses layout-aware motion so page entries keep the same fluid shifting behavior when the visible range changes.

PaginationLink, PaginationPrevious, PaginationNext, and PaginationEllipsis

2 props

These primitives expose the numbered buttons and edge controls individually while keeping the existing visual behavior intact.
isActiveboolean
Marks the current page on PaginationLink and keeps the underline anchored under the active number.
textstring
Optional label override for PaginationPrevious and PaginationNext. They default to Prev and Next.

Notes

Previous and next keep the same hover arrow nudge and current label treatment from the approved design.
Ellipsis markers remain static separators and are not interactive.