Pagination
Also called pager, page numbers, or paging
Navigation that splits a long list into numbered pages with Previous and Next buttons, so people browse a fixed number of items at a time.
const SIBLINGS = 1; // pages shown on each side of the current one
const NAV =
'flex items-center gap-1 text-sm font-medium *:flex *:h-9 *:min-w-9 *:items-center *:justify-center *:rounded-lg *:px-3 *:tabular-nums *:enabled:not-aria-[current]:hover:bg-muted *:disabled:opacity-40 *:aria-[current=page]:bg-primary *:aria-[current=page]:text-primary-foreground';
// 1 … 4 5 6 … 20: always the first and last page, plus the current page's neighbors.
function pageItems(current: number, total: number) {
const items: (number | 'gap')[] = [];
for (let page = 1; page <= total; page++) {
if (page === 1 || page === total || Math.abs(page - current) <= SIBLINGS)
items.push(page);
else if (items.at(-1) !== 'gap') items.push('gap');
}
return items;
}
type Props = { page: number; pages: number; onChange: (page: number) => void };
// Keep the page in the URL (?page=3) in the parent so it survives a refresh.
export function Pagination({ page, pages, onChange }: Props) {
return (
<nav aria-label='Pagination' className={NAV}>
<button disabled={page === 1} onClick={() => onChange(page - 1)}>
Previous
</button>
{pageItems(page, pages).map((item, index) =>
item === 'gap' ? (
<span key={`gap-${index}`}>…</span>
) : (
<button
key={item}
aria-current={item === page ? 'page' : undefined}
onClick={() => onChange(item)}
>
{item}
</button>
)
)}
<button disabled={page === pages} onClick={() => onChange(page + 1)}>
Next
</button>
</nav>
);
}Paginate the orders table at 10 rows per page. Under the table show Previous, Next, and page numbers with the current page highlighted, collapse long ranges into an ellipsis (1 … 4 5 6 … 20), and disable Previous on page 1 and Next on the last page. Keep the page in the URL as ?page=3, and crossfade the rows over 150ms when the page changes.
Paste into Layerwise or any AI coding tool.
What is Pagination?
Pagination breaks a long set of results into pages of, say, 10 or 25 items and puts a row of controls under the list: Previous, Next, and page numbers, with an ellipsis when there are too many pages to show at once (1 … 4 5 6 … 20).
Choose pagination when people look for something specific or need to find it again: search results, orders, invoices, admin tables. Every item has a stable spot, so “it was on page 3” means something, the footer stays reachable, and the page number can live in the URL for sharing and bookmarking.
Keep the controls in the same place on every page so people can click Next repeatedly without moving the mouse. Highlight the current page, disable Previous on the first page, and scroll the top of the list back into view after a page change.
Often confused with
- Infinite scroll
- Infinite scroll keeps adding items to one endless list as you near the bottom. Pagination splits items into numbered pages that people move between on purpose.
Related terms
All termsInfinite scroll
A list that loads the next batch of items automatically as you scroll near the bottom, so the feed seems to never end.
Data table
A table built for working with records: click a column header to sort, type to filter, and check rows to act on several at once.
Crossfade
A transition where the old content fades out while the new content fades in at the same spot, so the two briefly overlap.
Direction-aware transition
A transition that slides new content in from the side you are heading toward, so going forward and going back move in opposite directions.
Build it with Layerwise
Describe your app, watch it run in a live preview, and publish it with a database, storage, and sign-in built in.