Pagination
FreeMove through a long list or table one page at a time, with page numbers, a count and a page size.
npx wunderui-cli add paginationPlayground
Installation
npx wunderui-cli add paginationWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
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:
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
248 invoices
Showing 21–30
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.
Showing 10 invoices per page
Page 1 of 24
Keyboard interactions
Every control is a native button, field or select, so the browser provides focus and activation.
- TaborShift+Tab
- 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.
- 1data-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.
- 2
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.
- 3
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.
- 4
The page you are on, marked as the current page. Primary fills it with the brand colour, subtle sets it on a quiet surface.
- 5data-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.
| Prop | Type | Default | Description |
|---|---|---|---|
| page required | number | — | The current page, counting from 1. It is a controlled value: update it in . |
| pageCount required | number | — | 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. |
| showEdges | boolean | false | Adds a first-page and a last-page button at the two ends of the row. |
| className | string | — | 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| page required | number | — | The current page, counting from 1. It is shown in the label. |
| pageCount required | number | — | 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. |
| className | string | — | 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| page | number | — | Current page, 1-based. Together with it gives the range "1–10". |
| pageSize | number | — | Rows per page. |
| total | number | — | Total number of rows. Leave it out when the total is not known. |
| itemCount | number | — | 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. |
| noun | string | "result" | Singular noun for the total, "result" in "248 results". |
| nounPlural | string | — | Plural noun, defaults to + "s". |
| errorMessage | ReactNode | — | Shown instead of the default message while . |
| onRetry | () => void | — | Makes the error state show a "Retry" button. |
| className | string | — | 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| value required | number | — | Current page size. |
| onValueChange required | (value) => void | — | Called with the number of rows the person chose. Reset the page to 1 here. |
| options | number[] | [10, 25, 50, 100] | Choices in the menu. Default 10, 25, 50, 100. |
| label | string | "Rows per page" | Visible label. Default "Rows per page". |
| disabled | boolean | — | Disables the select, for example while a page loads. |
| className | string | — | 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| pageCount required | number | — | 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 ). |
| label | string | "Go to page" | Visible label. Default "Go to page". |
| buttonLabel | string | "Go" | Text of the button. Default "Go". |
| disabled | boolean | — | Disables the field and the button. |
| className | string | — | 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.
get_component("pagination")npx wunderui-cli add paginationThe full library index for assistants is at /llms.txt.
Related components
Recent invoicesInvoices issued in the last 30 days Invoice Status Customer Amount INV-2041 Paid WunderUI $24,800.00 INV-2040 Open Halcyon Labs $3,200.00 INV-2039 Overdue Pergola Foods $980.00 INV-2038 Paid Marlow & Finch $12,400.00 Total Sum$41,380.00 Core Elements5 stylesTableRows and columns with 23 ready-made cell types; for sorting and search use Data Table.- Checkout redesignCart, address and payment steps.Design tokens v2One source for colour, type and spacing.Billing portalInvoices, plans and payment methods.AnalyticsTraffic, conversion and retention.OnboardingA short tour for new teammates.Core Elements3 stylesCarouselA horizontally scrollable row of items with arrow controls.