Pagination

import * as React from "react"

import {

When to use it#

Use pagination when a list or a table has too many rows to show at once, and people need to jump to a particular page: orders, customers, search results. For a feed that people scroll through, a "load more" button is usually a better fit.

Pagination only draws the controls. You hold the current page in state, and you fetch or slice the rows yourself.

Import#

Copyimport {
  Pagination,
  PaginationControl,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationPrevious,
  PaginationNext,
  PaginationEllipsis,
  PaginationPageInfo,
  PaginationRowSelector,
  PaginationRowSelectorLabel,
  usePagination,
} from "@hel/ui/pagination"

Anatomy#

Pagination is the navigation landmark, named "Pagination" for screen readers. Inside it, PaginationControl holds the row of buttons: PaginationPrevious, the page list, and PaginationNext. The page list is a PaginationContent with one PaginationItem for each page.

A PaginationLink is one page button. Set isActive on the current page, which marks it as the current page for screen readers and gives it the selected look. Previous, Next and the page buttons are all buttons from the library, so they take onClick and disabled.

Building the page list#

usePagination works out which numbers and gaps to show, so you do not. Give it the current page (counting from 1) and the pageCount, and it returns a list. Each entry is a page number or an ellipsis marker.

Copyconst items = usePagination({ page, pageCount })
 
items.map((item) =>
  typeof item === "number" ? (
    <PaginationLink isActive={item === page} onClick={() => setPage(item)}>{item}</PaginationLink>
  ) : (
    <PaginationEllipsis />
  )
)

The list keeps the same length as people move through the pages, so the buttons do not jump around. When there are only a few pages, it just lists them all. siblings is how many pages to show on each side of the current one, and boundary is how many to always show at the start and the end. Both default to 1.

Examples#

With a table#

For a data table, add the rows per page menu and the page info. PaginationRowSelector holds a label and a Select. PaginationPageInfo says where you are. When the number of rows per page changes, the page count changes with it, so go back to the first page too.

import * as React from "react"

import {

Previous and next only#

When people only move one page at a time, or you do not know how many pages there are, leave out the numbers.

import * as React from "react"

import {

Text and direction#

The words in Previous and Next, and the name of the navigation, come from the app's config, in the language of the app. Pass your own children to PaginationPrevious or PaginationNext to change them for one place. In a right-to-left layout, Previous moves to the right, and its arrow points the way earlier pages are.

Props#

usePagination#

PaginationLink#

It also takes the props of a Button, and defaults to a ghost, square, medium button.

The other parts#