Skip to content
WunderUI

Pagination

Free

Move through a long list or table one page at a time, with page numbers, a count and a page size.

npx wunderui-cli add pagination

Playground

Installation

bash
npx wunderui-cli add pagination

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import {
  Pagination,
  PaginationJump,
  PaginationPageSize,
  PaginationSimple,
  PaginationSummary,
} from "@/components/ui/pagination"
import type {
  PaginationCurrentStyle,
  PaginationJumpProps,
  PaginationPageSizeProps,
  PaginationProps,
  PaginationShape,
  PaginationSimpleProps,
  PaginationSummaryProps,
} from "@/components/ui/pagination"

Then use it:

tsx
import { useState } from "react"
import { Pagination } from "@/components/ui/pagination"

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

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

Expected result: You see a disabled Prev button, pages 1 and 2, an ellipsis, page 12 and Next, with page 1 filled. Click 2 or Next to move the current page.

When to use

Use Pagination for

  • Long tables and lists where people need to reach a specific page, such as invoices or members
  • Search results, where position matters and people go back to a result they saw
  • Server-side data, where every page is its own request

Use something else for

  • Tabs for peer views of one object, not pages of one list
  • Breadcrumb for the path of a page inside the product
  • Carousel for a few slides or cards that people move through one at a time

Layout

Pagination shows numbered pages between Prev and Next, or use PaginationSimple when only Prev, Next and the page count fit. Below 640 px the labels hide and leave the arrows.

Position

The row always shows the first page, the last page and the pages around the current one. Prev is disabled on the first page and Next on the last; click a number to see the ellipsis move.

Summary

PaginationSummary tells people where they are: a range of a total, the total alone, a range without a total, a loading skeleton, or an error with a Retry button.

21–30 of 248

Controls

PaginationPageSize lets people choose how many rows a page holds, and PaginationJump takes them to a page by number. Type 99 in the jump field and press Enter to see the error.

Rows per page

Showing 10 invoices per page

Keyboard interactions

Every control is a native button, field or select, so the browser provides focus and activation.

TaborShiftTab
Moves focus to the next or previous enabled button. A disabled Prev or Next and the ellipsis are skipped.
EnterorSpace
Goes to the focused page, or one page back or forward from Prev and Next, or to the first or last page from the edge buttons.
Enter
In the jump field: goes to the typed page. A number outside 1 to , or no whole number, shows an error and stays where it is. It does not submit a form around the pager.
ArrowDownorArrowUp
In the open page size menu: moves between the sizes. Enter or Space on the closed select opens the menu, Enter chooses the highlighted size and Escape closes it.

Behavior and motion

What the pager does with state, the page list, the edges and motion.

Controlled
Pagination keeps no state: the page comes from you, and every click reports the new number. Nothing changes until you set the page.
Which pages show
The first page, the last page and the current page with one neighbour each side always show, so the row holds at most seven items. Gaps fold into an ellipsis, which can stand for a single page.
Edges
Prev and Next are disabled on the first and last page: they keep their place, drop to 40% opacity and are skipped by Tab. The edge buttons follow the same rule.
Current page
The current page stays a button, so choosing it again reports the same number. Hover tints a page with the page background and pressed with the subtle one; the current page keeps its own fill.
Narrow screens
Below 640 px Prev and Next show only the arrow. The row never wraps and is about 340 px wide on a phone (412 px with edge buttons), so in a narrower space allow wrapping or use PaginationSimple.
Summary states
Loading shows a skeleton and announces Loading results. Error is an alert saying the count could not load, with a Retry button if you set a retry handler, and a total of 0 reads No results.
Jump errors
The error text of PaginationJump sits under the row without making it taller, so a form around it does not move. The input stays marked invalid until the next edit.
Numbers and direction
Counts use the English format with a comma, such as 1,248. The chevrons turn 180 degrees in right-to-left layouts.
Motion
Nothing slides: the current page changes in place. Page buttons change colour at the base speed; Prev, Next and the edge buttons a little faster.
Reduced motion
There is no movement to remove, so reduced motion changes nothing. The colour changes are short fades and stay.

Anatomy

The figure marks the Pagination row with first and last page buttons. PaginationSimple, PaginationSummary, PaginationPageSize and PaginationJump are separate parts that sit beside it or replace it.

  • data-slot="pagination"

    A nav named Pagination with Prev and Next around numbered page buttons. You hold the page and change it in the page change handler; options are shape, current style and first and last buttons.

  • data-slot="pagination-first"Optional

    The first-page and last-page buttons at the two ends, shown with the edges option. Each is an icon button named First page or Last page.

  • Text buttons with a chevron: Prev is disabled on the first page and Next on the last. Below 640 px the text hides and the chevron stays, and screen readers still read the text.

  • A numbered button that goes to its page. The row always shows the first page, the last page and the pages around the current one.

  • The page you are on, marked as the current page. Primary fills it with the brand colour, subtle sets it on a quiet surface.

  • data-slot="pagination-ellipsis"Optional

    Stands for the pages that are folded away. It is plain text, not a button.

  • data-slot="pagination-last"Optional
  • data-slot="pagination-simple"Optional

    The compact form: Previous and Next with a Page X of Y label between them, for narrow spaces. It takes the same shape.

  • data-slot="pagination-summary"Optional

    The count line: a range of a total (21 to 30 of 248), the total alone, a range without a total, a loading skeleton, or an error with a Retry button.

  • data-slot="pagination-page-size"Optional

    A labelled select for the number of rows per page. Its label is the accessible name of the select.

  • data-slot="pagination-jump"Optional

    A labelled number field with a Go button. Enter or Go jumps to the page; a value outside 1 to the page count shows an error under the row.

Best practices

  • Do

    Keep the page in state and load the matching rows in the page change handler. Pages count from 1, and the page count is the total number of pages.

  • Do

    Show where people are with PaginationSummary next to the pager, such as 21 to 30 of 248. When the total is unknown, leave it out and it says Showing 21 to 30.

  • Do

    Reset the page to 1 when the page size, a filter or a search changes. Otherwise people can land on a page that no longer exists.

  • Do

    Use PaginationSimple where only Previous and Next fit, such as a narrow card or a phone, and keep the count in PaginationSummary above the list.

  • Don’t

    Don't build page buttons by hand. Pagination already disables Prev on the first page and Next on the last, and marks the current page.

  • Don’t

    Don't show a pager for one page. With a page count of 1 it shows a lone 1; hide it instead.

  • Don’t

    Don't use Pagination for a feed that grows as people read. A list that appends more rows needs a Load more button or an infinite list, not pages.

  • Don’t

    Don't let the page leave the range 1 to the page count. Pagination does not clamp it, so a stale page shows a row with no current number.

API reference

One table per part, and none wraps a primitive, so each lists every prop. Pagination is controlled: you own the current page.

A nav named Pagination with Prev and Next around numbered page buttons. You hold the page and change it in the page change handler; options are shape, current style and first and last buttons.

PropTypeDefaultDescription
page requirednumber—The current page, counting from 1. It is a controlled value: update it in .
pageCount requirednumber—The total number of pages. The last button and the end of the page list follow it.
onPageChange required(page) => void—Called with the page the person chose: a number, or one before or after the current page from Prev and Next.
shape"rounded" | "pill""rounded" gives the buttons 8 px corners and is the default; rounds every button fully.
currentStyle"primary" | "subtle""primary"How the current page is drawn: fills it with the brand colour and is the default, marks it with a quiet surface.
showEdgesbooleanfalseAdds a first-page and a last-page button at the two ends of the row.
classNamestring—Extra classes for the , for example on a narrow container.

The compact form: Previous and Next with a Page X of Y label between them, for narrow spaces. It takes the same shape.

PropTypeDefaultDescription
page requirednumber—The current page, counting from 1. It is shown in the label.
pageCount requirednumber—The total number of pages, shown as the Y of the label. Next is disabled on the last page.
onPageChange required(page) => void—Called with the previous or the next page when a button is pressed.
shape"rounded" | "pill""rounded" gives both buttons 8 px corners and is the default; rounds them fully.
classNamestring—Extra classes for the . The row spreads Previous, the label and Next across its width.

The count line: a range of a total (21 to 30 of 248), the total alone, a range without a total, a loading skeleton, or an error with a Retry button.

PropTypeDefaultDescription
pagenumber—Current page, 1-based. Together with it gives the range "1–10".
pageSizenumber—Rows per page.
totalnumber—Total number of rows. Leave it out when the total is not known.
itemCountnumber—Rows on the current page, for an unknown total or a short last page. Defaults to .
status"ready" | "loading" | "error""ready""loading" shows a skeleton, "error" says the count failed and offers a retry.
nounstring"result"Singular noun for the total, "result" in "248 results".
nounPluralstring—Plural noun, defaults to + "s".
errorMessageReactNode—Shown instead of the default message while .
onRetry() => void—Makes the error state show a "Retry" button.
classNamestring—Extra classes for the text, the skeleton or the error row.

A labelled select for the number of rows per page. Its label is the accessible name of the select.

PropTypeDefaultDescription
value requirednumber—Current page size.
onValueChange required(value) => void—Called with the number of rows the person chose. Reset the page to 1 here.
optionsnumber[][10, 25, 50, 100]Choices in the menu. Default 10, 25, 50, 100.
labelstring"Rows per page"Visible label. Default "Rows per page".
disabledboolean—Disables the select, for example while a page loads.
classNamestring—Extra classes for the row that holds the label and the select.

A labelled number field with a Go button. Enter or Go jumps to the page; a value outside 1 to the page count shows an error under the row.

PropTypeDefaultDescription
pageCount requirednumber—The total number of pages. A typed page must be a whole number from 1 to this value.
onPageChange required(page) => void—Called with a valid page (a whole number from 1 to ).
labelstring"Go to page"Visible label. Default "Go to page".
buttonLabelstring"Go"Text of the button. Default "Go".
disabledboolean—Disables the field and the button.
classNamestring—Extra classes for the row that holds the label, the field and the button.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("pagination")
Installnpx wunderui-cli add pagination

The full library index for assistants is at /llms.txt.