Pagination

When to use

Search results or a long table split into pages
Moving to the next or previous page, or jumping to one

Not for a few steps of a form — show the steps instead — or a short list that fits on one page.

Choosing between moving around:

Component	Use it for	For example
Breadcrumb	Showing where the page sits in a hierarchy, with links up it	Home / Projects / Website
Pagination	Moving between pages of one long list	Search results, page 3 of 12
Tabs	Switching between views within one page	Overview / Activity / Settings
Link	One destination	“Read the docs”

Showing page 6 of 20.

import { useState } from 'react';
import { Pagination } from '@arun-dev/ui';

// Buttons, with the page in state. With pages as URLs, pass getHref instead.
export default function PaginationBasics() {
  const [page, setPage] = useState(6);
  return (
    <div style={{ display: 'grid', gap: 'var(--space-sm)' }}>
      <Pagination page={page} count={20} onPageChange={setPage} />
      <p style={{ margin: 0 }}>Showing page {page} of 20.</p>
    </div>
  );
}

Pagination shows the first and last pages, the current one with its neighbours, and an ellipsis for the rest. It always uses the same number of slots, so the row doesn’t change width as you move. The current page is marked aria-current="page".

Links or buttons

The page is yours, so page and count are always given:

Pages are URLs (?page=3): pass getHref, and each page is a link. Opening one in a new tab works, and so does the back button.
Pages are state: pass onPageChange, and each page is a button.

<Pagination page={page} count={20} getHref={(p) => `?page=${p}`} />
<Pagination page={page} count={20} onPageChange={setPage} />

On the first or last page, Previous or Next is disabled. As a link it becomes plain text, since a link can’t be disabled.

Your own layout

paginationRange(page, count, siblings) returns the entries the component shows, numbers and 'ellipsis', so a layout of your own can use the same rules.

Props

Pagination props
Prop	Type	Default	Description
`page`	`number`		The current page, from 1. Required.
`count`	`number`		How many pages there are. Required.
`siblings`	`number`	`1`	Pages shown either side of the current one.
`getHref`	`(page: number) => string`		Each page's address: pages become links. The right choice when pages are URLs.
`onPageChange`	`(page: number) => void`		Called with the page to go to. Without `getHref`, pages are buttons that call it.
`labels`	`{ previous?, next?, page? }`		Text of Previous and Next, and each page's accessible name — `(p) => 'Page ' + p` by default.