Pagination

Pagination allows you to divide large amounts of content into smaller chunks across multiple pages.

Import#

import { Pagination } from '@volue/wave-react';

// Optional hook that computes range of page numbers
import { usePagination } from '@volue/wave-react';

Pagination is a compound component that consists of multiple parts to help you create different kinds of pagination.

Pagination: The outer pagination container with the accessible role=navigation.
Pagination.Arrow: Left and right arrow controls with optional text labels.
Pagination.Numbers: A wrapper for the list of page numbers.
Pagination.Number: Page number controls.
Pagination.Ellipsis: Indicates there are remaining pages.
Pagination.Label: Indicates the current page in view (e.g., "Page 2", "1–10 of 50 results").

Examples#

Minimal#

At minimum, the Pagination should display arrows to navigate to the previous and next set of items in the paged dataset. However whenever possible, show the current page number too, so that users know where they are in a dataset.

Hint when users are at the first or the last page by disabling the corresponding Pagination.Arrow.

Pagination with custom labels#

You may change the text labels shown to the user to provide users more information about what kind of data is in view and in what direction the pages are moving.

Number pagination#

Pagination makes it easy to display a list of page numbers for your users, so that they may easily navigate larger datasets.

Pagination is commonly paired with tables, see Table component.

Number pagination with label#

Use Pagination.Label for contextual information, like the current range of items.

To keep the design simple on mobile, only the current range/page, next and previous arrows can be displayed, by adding is-visibleLarge class to Pagination.Numbers.

Sizes#

Use size prop to control the size of the Pagination. medium and small sizes are available, with the medium size used by default.

With pagination hook#

Wave exports usePagination hook that gives you a range of numbers to be rendered by the Pagination. The hook accepts the following props:

pageCount: represents the total number of pages.
currentPage: represents the current active page (uses a 1-based index).
siblingCount represents the min number of page numbers to be shown on each side of the current page (defaults to 1).

const paginationRange = usePagination({
  currentPage: 1,
  pageCount: 10
});

When the total number of pages exceeds siblingCount + 5, the page numbers are truncated using an ellipsis. Double truncation is used when there is more than one page number to be inserted between the extremes of sibling and the page limits.

By default, usePagination will ensure that a maximum of seven pages (including the Pagination.Ellipsis) are shown.

Pagination as anchor#

Pagination navigates by the use of a button by default. However, both the Pagination.Arrow and Pagination.Number can be set as anchors using the as="a" prop and including an href prop.

Use anchors if the URL changes for each page.

API Reference#

Pagination#

Prop	Type	Default
`as`	`enum`	`nav`
`css`	`StitchesCss`	No default value
`size`	`enum`	`medium`
`label`*	`string`	No default value

Pagination.Label#

Prop	Type	Default
`as`	`enum`	`div`
`css`	`StitchesCss`	No default value
`color`	`ColorToken`	No default value

Pagination.Arrow#

Prop	Type	Default
`as`	`enum`	`button`
`css`	`StitchesCss`	No default value
`direction`*	`enum`	No default value
`label`	`string`	No default value
`visibleLabel`	`string`	No default value
`isDisabled`	`boolean`	`false`

Pagination.Numbers#

Prop	Type	Default
`css`	`StitchesCss`	No default value

Pagination.Number#

Prop	Type	Default
`as`	`enum`	`button`
`css`	`StitchesCss`	No default value
`label`*	`string`	No default value
`variant`	`enum`	`"ghost"`
`isCurrent`	`boolean`	`false`
`isDisabled`	`boolean`	`false`

Pagination.Ellipsis#

Prop	Type	Default
`css`	`StitchesCss`	No default value
`label`*	`string`	No default value

usePagination#

Prop	Type	Default
`currentPage`*	`number`	No default value
`pageCount`*	`number`	No default value
`siblingCount`	`number`	`1`