Pagination

Moves between the pages of a paged list. Each number renders as a Button.

import { Pagination } from 'neba';

<Pagination count={24} page={page} onPageChange={setPage} showEdges />;

Props

Prop	Type	Default	Description
locale	string	—	BCP 47 tag: the nav name, the page buttons, the arrows and the status sentence
variantshared	'solid' | 'outline' | 'text'	'text'	How the pages look at rest. The current page is always solid: the one thing the row has to say without being read, which is also why the default here is text: nine filled buttons in a row say all nine are the primary action
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	The buttons’ height and type scale. They are real Buttons, so a lg pagination lines up with a lg button beside it
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. Arbitrary colour values are not accepted
densityshared	'default' | 'compact'	'compact'	Padding only: never the height, never the type scale
elevationshared	0 | 1 | 2 | 3	0	Drop shadow depth. 0 means no shadow at all
count *	number	—	How many pages there are. Fewer than two and the whole control renders nothing: a row advertising that it has nothing to do is not a control
page	number	—	The current page, 1-based, for a controlled set
defaultPage	number	1	Which page starts current
onPageChange	(page: number) => void	—	Called when the page changes
siblingCount	number	1	How many pages are always shown on either side of the current one
boundaryCount	number	1	How many pages are always shown at each end. 0 drops the first and last page, leaving only the window
showEdges	boolean	false	Shows the jump-to-first and jump-to-last steppers
showArrows	boolean	true	Shows the previous and next steppers
disabled	boolean	false	Unavailable. Every button in the row stops answering
getPageHref	(page: number) => string	—	The address of a page. Turns the numbers into real links a crawler can follow, and marks the two arrows rel="prev" / rel="next"
label	string	—	Accessible name of the nav landmark
pageLabel	(page: number) => string	—	Accessible name of a page button. Defaults to the locale's wording
previousLabel	string	—	Accessible name of the previous stepper
nextLabel	string	—	Accessible name of the next stepper
firstLabel	string	—	Accessible name of the first-page stepper
lastLabel	string	—	Accessible name of the last-page stepper

A count of 1 renders nothing at all.

Examples

variant

variant is how the page buttons look when they are not the current page. The current page is always filled, whatever the variant.

The default is text rather than Button's solid: several filled buttons in a row leave no way to tell which page you are on.

import { Pagination, Typography } from 'neba';

/**
 * `variant` is how the pages look *at rest*. The current page is always filled,
 * whatever the row's resting variant is — it is the one thing here that has to
 * be legible without being read.
 */
export default function PaginationVariants() {
  return (
    <div className="flex flex-col gap-5">
      {(['text', 'outline', 'solid'] as const).map((variant) => (
        <div key={variant} className="flex flex-col gap-1">
          <Typography level="caption">variant="{variant}"</Typography>
          <Pagination count={9} defaultPage={4} variant={variant} />
        </div>
      ))}
    </div>
  );
}

siblingCount · boundaryCount · showEdges · showArrows

siblingCount is how many numbers show either side of the current page; boundaryCount how many always show at each end. showEdges adds first/last buttons and showArrows adds previous/next.

The number of slots in the row stays constant as the page changes. The window slides toward whichever end it is near rather than being clipped by it, so the buttons never move out from under the pointer that just pressed one. A gap of exactly one page is filled with that page rather than an ellipsis.

import { Pagination, Typography } from 'neba';

/**
 * The window slides toward whichever end it is near rather than being clipped by
 * it, so the row keeps the same number of slots on every page. Which slots are
 * pages and which are ellipses changes; how many there are does not — otherwise
 * stepping from page 1 to page 2 would relayout the row and move every button
 * out from under the pointer that just pressed one.
 */
export default function PaginationRange() {
  return (
    <div className="flex flex-col gap-5">
      {[1, 2, 10, 19, 20].map((page) => (
        <div key={page} className="flex flex-col gap-1">
          <Typography level="caption">page={page}</Typography>
          <Pagination count={20} page={page} showArrows={false} />
        </div>
      ))}

      <div className="flex flex-col gap-1">
        <Typography level="caption">
          siblingCount={2} · boundaryCount={2}
        </Typography>
        <Pagination count={20} page={10} siblingCount={2} boundaryCount={2} showArrows={false} />
      </div>
    </div>
  );
}

size

import { Pagination } from 'neba';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const;

export default function PaginationSizes() {
  return (
    <div className="flex flex-col gap-4">
      {SIZES.map((size) => (
        <Pagination key={size} size={size} count={9} defaultPage={4} />
      ))}
    </div>
  );
}

getPageHref

Return the address of a page and the numbers in the row become real <a href>. A crawler cannot press a button, so without this everything past page one of a list does not exist to a search engine. The browser's own behaviour comes back with it: open in a new tab, copy the address, see where a press goes before making it. The two arrows carry rel="prev" and rel="next".

Pass onPageChange alongside it and the navigation is cancelled for the handler to answer: the shape a client-side router wants, keeping the page it already has. With no handler, the link does what a link does. A press carrying a modifier key is always left to the browser.

The page being read and an arrow at the end of the row stay <button>. An <a> cannot be disabled, so one left as a link is one a keyboard still lands on and a crawler still follows.

import { useState } from 'react';
import { Pagination, Typography } from 'neba';

/**
 * The same row twice. Above, `getPageHref` alone: every number is an `<a href>`
 * and pressing one is a navigation, which is what a crawler follows and what a
 * middle-click opens in a new tab. Below, the same links with a handler behind
 * them — the press is cancelled and the page stays, which is the shape a
 * client-side router wants.
 */
export default function PaginationLinks() {
  const [page, setPage] = useState(3);

  return (
    <div className="flex flex-col gap-5">
      <div className="flex flex-col gap-1">
        <Typography level="caption">getPageHref</Typography>
        <Pagination count={12} page={3} getPageHref={(value) => `/posts?page=${value}`} />
      </div>

      <div className="flex flex-col gap-1">
        <Typography level="caption">getPageHref + onPageChange</Typography>
        <Pagination
          count={12}
          page={page}
          getPageHref={(value) => `/posts?page=${value}`}
          onPageChange={setPage}
        />
      </div>
    </div>
  );
}

Accessibility

• Renders a <nav> around a <ul>, with aria-current="page" on the current page.
• The ellipsis is punctuation rather than a control, so it is not rendered as a disabled button.
• With getPageHref the numbers are links, so they appear in a screen reader's list of links and a keyboard reader can see where each one goes.
• Every accessible name is settable: label · pageLabel · previousLabel · nextLabel · firstLabel · lastLabel. With more than one pagination on a screen, use label to say what each one paginates.
• locale decides the nav name, the page buttons, the arrows and the sentence that reads out where you are. Each of them takes a string of its own.