Skip to content
flyingsalmon

Pagination

The control that moves between the numbered pages of one list or table whose page count is known.

Installation

npx shadcn@latest add @flyingsalmon/pagination

Usage

import { useState } from 'react'

import { Pagination } from '@/components/ui/pagination'

export function PaginationUsage() {
  const [page, setPage] = useState(1)

  return <Pagination page={page} pageCount={12} onPageChange={setPage} />
}

Examples

Short list

Five pages fit in the seven slots, so every page shows and no ellipsis appears. The component decides from pageCount; there is nothing to configure.

Compact

Where the row has no space for numbers (a toolbar, a card footer, a phone-width list) the numbers give way to the position. Previous and next keep their size.

Custom position text

formatPageLabel writes the compact text yourself, for another wording or another language.

Under a table

Pagination is the control, not the data. It sits right-aligned under the table it pages; the slicing and the fetching stay in your app.

PlaceNeighbourhoodDay
Fushimi InariFushimiDay 1
Kiyomizu-deraHigashiyamaDay 1
Nishiki MarketNakagyoDay 1

Guidelines

When to use

  • To page through one list or table whose page count is known, such as the places saved to a trip.
  • When the traveller needs to land on a specific page and come back to it, in the URL or in state.

When not to use

  • Use Stepper for a position in a short sequence someone is walking, because stepper only shows where they are and never navigates.
  • Use Breadcrumb to climb the levels above the current page, because pagination moves across siblings and never up.
  • Use Tabs to move between peer panels of content rather than pages of data.

Do and don’t

  • Do
    Right-align pagination under the list it pages, once per list.It waits where the traveller finishes reading. A second copy above the list is one more thing to scan and nothing new to do.
  • Do
    Keep the page number in the address whenever the traveller can land on a page.A page in the URL can be bookmarked, shared, opened in a new tab, and reloaded, so the traveller comes back to the page they left rather than to page 1.
  • Do
    Write a line such as "1 to 20 of 240" beside the list when the traveller needs the total.Pagination shows where the traveller is, not how much there is. Only the app knows the size of its data.
  • Don’t
    Show pagination on a list that fits on one page.A row with one number offers a choice that is not there, so a one-page list simply ends.
  • Don’t
    Page a short list that grouping or filtering would keep on one screen.Trips split into upcoming and past stay in view together. A page break hides half of them behind a press.

Accessibility

KeyDescription
TabMoves through previous, the page items, and next. A disabled previous or next takes no focus.
EnterSpaceActivates the focused item. On the current page it changes nothing and focus stays put.

The root is a nav named “Pagination”; aria-label overrides the name. Each page item is named “Page 5” and the current one carries aria-current="page". Previous and next are named “Previous page” and “Next page”, the ellipsis is hidden from the accessibility tree, and the compact text is a polite live region, so a screen reader hears the new position without being interrupted.

There are no arrow keys: pagination is a navigation region of independent controls, not a composite widget. Items are keyed by page number, so focus stays on the page you activated even when the window shifts around it and you can keep stepping without hunting for focus.

API

Pagination

Controlled: the row count, the page size, and the fetching stay in your app, and so do “Load more”, infinite scroll, a page-size select, and a range line. Also takes every <nav> attribute except children.

PropTypeDefaultDescription
pagenumberRequiredThe current page, counting from 1.
pageCountnumberRequiredThe number of pages. A value of 1 or less renders nothing.
onPageChange(page: number) => void–Called with the target page. It is not called for the current page.
compactbooleanfalseReplaces the page numbers with the position text between previous and next. The component never measures its width and has no breakpoint, so you choose compact where the row has no room for numbers: a toolbar, a card footer, a phone-width list.
formatPageLabel(page: number, pageCount: number) => string"Page {page} of {pageCount}"Writes the compact position text.
renderPageLink(page: number, children: ReactNode) => ReactNode–Renders each page item and each enabled previous or next as the anchor you return. Pass it when the page lives in the URL. A disabled previous or next stays a plain span.
aria-labelstring"Pagination"The name of the nav landmark.

  • Table

    The data most paginations sit under.
  • Stepper

    A display-only position in a short sequence.
  • Breadcrumb

    The trail of ancestors above the current page.
  • Tabs

    Peer panels of content rather than pages of data.