Pagination

Server component, no client JS

ImportCopy Anchor Link

import { Pagination } from '@nizivo/react/pagination';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css
import '@nizivo/react/css/pagination.css';

Static or interactiveCopy Anchor Link

Server. It ships no client JavaScript when a Server Component renders it, in every Next.js build mode; its code is bundled only when a client component (a 'use client' file) imports it. It has two modes:

• Links (getHref): the page is in the URL, getHref(page) gives each page's URL, and the current page is aria-current="page". getHref, and a function renderLink, run where Pagination renders, so a Server Component passes them directly; a router link passed through renderLink is the router's own code.
• Buttons (onPageChange), for client state with no URL: each page, previous and next is a <button type="button">, and choosing another page calls onPageChange(page, details) (details.reason is 'page', 'previous' or 'next') with no navigation. The ends are disabled buttons. Pass it from a client component, for example onPageChange={setPage}. It adds no client module of its own. In a client app has a live demo.

How to choose.

Which pages showCopy Anchor Link

The first and last boundaryCount pages always show, and so do siblingCount pages on each side of the current one. A gap becomes "…" unless it would hide a single page, which shows instead. With the defaults (1 and 1) that is 7 page slots once there are more than 7 pages, wherever the current page is: 1 2 3 4 5 … 13, 1 … 6 7 8 … 13, 1 … 9 10 11 12 13. Figma's drawing (1 2 3 … 13) is siblingCount={0}. The rule is internal (the tests cover it); it is not exported. With previous and next, the defaults take 9 slots: 392 px at size="md" (40 px squares) and 320 px at sm (32 px). In a narrower container the slots wrap, so use sm and siblingCount={0} there (7 slots, 248 px).

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { Pagination } from '@nizivo/react/pagination';

export function PaginationExample(): JSX.Element {
  return (
    <Pagination
      page={1}
      totalPages={13}
      getHref={(page) => `?page=${page}`}
      summary="Showing 1–20 of 248"
    />
  );
}

import type { ComponentPropsWithRef, JSX } from 'react';
import { Pagination } from '@nizivo/react/pagination';

/** Stands in for a router link (Next `Link`, React Router `Link`). */
function Link({ children, ...props }: ComponentPropsWithRef<'a'>): JSX.Element {
  return <a {...props}>{children}</a>;
}

export function PaginationRouterExample(): JSX.Element {
  return (
    <Pagination
      page={7}
      totalPages={13}
      siblingCount={0}
      size="sm"
      getHref={(page) => `/orders?page=${page}`}
      renderLink={<Link />}
    />
  );
}

PropsCopy Anchor Link

Other exportsCopy Anchor Link

PaginationChangeReason type

import type { PaginationChangeReason } from '@nizivo/react/pagination'

Which control asked for the page.

type PaginationChangeReason = "page" | "previous" | "next"

PaginationLabels type

import type { PaginationLabels } from '@nizivo/react/pagination'

Pagination's own strings (§16.4): serialisable, English defaults; {page} is replaced.

Name	Type	Default	Description
navrequired	string	'Pagination'	The landmark's name.
nextrequired	string	'Next page'
pagerequired	string	'Page {page}'	Each page link's name; the visible number stays in it (WCAG 2.5.3).
previousrequired	string	'Previous page'	The previous link's name (it shows only a chevron).

PaginationLinkState type

import type { PaginationLinkState } from '@nizivo/react/pagination'

Name	Type	Default	Description
currentrequired	boolean	–
kindrequired	"page" | "previous" | "next"	–
pagerequired	number	–	The page this link goes to.

PaginationProps type

import type { PaginationProps } from '@nizivo/react/pagination'

The props of Pagination, listed above.

PaginationSize type

import type { PaginationSize } from '@nizivo/react/pagination'

40 px (md) or 32 px (sm) squares; Figma's 36 px is off the control scale (figma/06).

type PaginationSize = "sm" | "md"

PaginationSlot type

import type { PaginationSlot } from '@nizivo/react/pagination'

One slot of the list: a page number or a gap.

type PaginationSlot = number | "ellipsis"

PaginationState type

import type { PaginationState } from '@nizivo/react/pagination'

The render state of Pagination, listed above.

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-glyph, .nz-pagination, .nz-pagination-ellipsis, .nz-pagination-icon, .nz-pagination-list, .nz-pagination-page, .nz-pagination-previous, .nz-pagination-step, .nz-pagination-summary.

AccessibilityCopy Anchor Link

These parts are interactive. Each gets the focus outline and touch-action rule from @nizivo/react/css/base.css (the nz.base layer), so the floor survives a restyle:

• pagination-next: draws the focus outline itself on keyboard focus.
• pagination-page: draws the focus outline itself on keyboard focus.
• pagination-previous: draws the focus outline itself on keyboard focus.

In forced-colours mode these states keep a visible system colour: pagination-page[aria-current='page'] (highlight).

KeyboardCopy Anchor Link

Source: native <a> elements in a <nav> (pagination.tsx, no client code). The browser lane (test/browser/pagination.spec.tsx) checks that on page 1 Tab skips the disabled previous link, visits every page link, then next, and the focus outline.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: Figma node 755:1007
• Ghost masters: none