Skip to the content
BooleanPress UI

Data

Pagination

Moves between the pages of a list, such as the email log.

Import

import { Pagination, PaginationContent, PaginationLink, PaginationItem, PaginationPrevious, PaginationNext, PaginationEllipsis } from "@booleanpress/ui/pagination"

Usage

Pagination is a navigation landmark holding a list of links. It draws the links and the current page; it does not know how many pages there are. You decide which numbers to show, when to add an ellipsis, and where each link goes.

import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "@booleanpress/ui/pagination"

export function Pages() {
  return (
    <Pagination>
      <PaginationContent>
        <PaginationItem><PaginationPrevious href="?page=1" /></PaginationItem>
        <PaginationItem><PaginationLink href="?page=2" isActive>2</PaginationLink></PaginationItem>
        <PaginationItem><PaginationNext href="?page=3" /></PaginationItem>
      </PaginationContent>
    </Pagination>
  )
}

Every part renders a plain <a>. In a single-page app, give it an onClick that calls preventDefault and changes the page (the As buttons example), or render your router's link. isActive marks the current page: it draws the outline button and sets aria-current="page". PaginationLink takes size from the button sizes.

The landmark name and the link labels (pagination, previous, next, previousPage, nextPage, morePages) come from the provider's strings, so a translated product sets them once on BooleanUIProvider.

Examples

Basic

Previous, three numbered pages with the second current, and Next.

With ellipsis

A long list shows the first and last page and the pages around the current one; PaginationEllipsis stands for the gap.

First page

On the first page, Previous is dimmed, skipped by Tab and marked aria-disabled.

As buttons

In a single-page app the links change state instead of the address; the current page is announced with aria-current.

Accessibility

Semantics
A nav landmark named by the pagination string, holding a ul. The current page is a link with aria-current="page". Previous and Next carry the previousPage and nextPage strings as aria-label, and the ellipsis is hidden from assistive technology.
Labels
A page needs a name that says what it is: a number alone is read as "2, link". Add aria-label="Page 2" to a number if the list around it does not make the meaning clear. If a page has more than one pagination, give each its own aria-label, because the strings give every one the same name.
Focus
Every link is a tab stop. The focus ring shows on keyboard focus. A link with no href is not a tab stop.
Known limits
  • There is no disabled state. For the first or last page, dim the link, remove it from the tab order (tabIndex={-1}) and set aria-disabled="true" yourself, as the First page example does, or leave the link out.
  • Previous and Next show only a chevron below the sm breakpoint; their accessible name stays.
  • A change of page is not announced. Move focus to the list heading, or announce the new page in a live region.

Keyboard

Keyboard
KeyBehaviour
TabMoves focus to the next link.
ShiftTabMoves focus to the previous link.
EnterFollows the focused link.

API

Pagination

Renders a nav and passes it every other prop.

PaginationContent

Renders a ul and passes it every other prop.

PaginationLink

PaginationLink props
PropTypeDefaultDescription
isActivebooleanMarks the current page: the outline style and aria-current="page".

PaginationItem

Renders a li and passes it every other prop.

PaginationPrevious

PaginationPrevious props
PropTypeDefaultDescription
isActiveboolean

PaginationNext

PaginationNext props
PropTypeDefaultDescription
isActiveboolean

PaginationEllipsis

Renders a span and passes it every other prop.

Every part takes className, merged with its defaults by cn(), and ref, which reaches the element it renders.

Data attributes: data-slot="pagination" (Pagination), data-slot="pagination-content" (PaginationContent), data-slot="pagination-link" (PaginationLink), data-slot="pagination-item" (PaginationItem), data-slot="pagination-ellipsis" (PaginationEllipsis), and data-active.

Provider strings: pagination, previousPage, previous, nextPage, next, morePages (BooleanUIProvider's strings).

Theming

The current page uses the outline button, the others ghost. The chevrons turn around in a right-to-left page, so Previous always points the way a reader goes back.

The tokens its classes read. Change their values in your theme, and it follows.

Theme tokens
TokenUsed for