Pagination

a control that enables selection of a single page from a range of pages

Props

a11yTitle

Custom label to be used by screen readers. When provided, an aria-label will be added to the element.

string

"a user friendly label for screen readers"

alignSelf

How to align along the cross axis when contained in a Box or along the column axis when contained in a Grid.

string

"start"

"center"

"end"

"stretch"

gridArea

The name of the area to place this inside a parent Grid.

string

"a parent grid area name"

margin

The amount of margin around the component.

string

"none"

"xxsmall"

"xsmall"

"small"

"medium"

"large"

"xlarge"

object

Can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.


{
    vertical: "...",
    horizontal: "...",
    top: "...",
    bottom: "...",
    left: "...",
    right: "..."
}

numberEdgePages

The number of pagination buttons visible at the start and end of page range.

number

numberItems

The total number of items to paginate.

number

numberMiddlePages

The number of pagination buttons visible in the middle of the controls.

number

onChange

Function called when the user clicks a page or arrow button.

function

The single argument is an event containing the target page via 'event.page', and the startIndex and endIndex for items contained in the target page via 'event.startIndex' and 'event.endIndex', respectively.

({ page, startIndex, endIndex }) => {...}

page

The default page. If used with onChange, it can be used to control the active page via state.

number

size

Specifies what size the pagination control buttons should be.

string

"small"

"medium"

"large"

step

The number of items per page.

number

React/DOM Properties

At its core, the Pagination component is a regular <nav> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for nav elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

Also, feel free to read about the types of React events available, or see how DOM attributes change in React. Working in tandem with Styled Components, you also have access to the as property.

Theme

pagination.button

Any valid Button theming to apply on the pagination buttons.

object

{
  active: {
    background: {
      color: 'active-background',
    },
  },
  color: 'text-strong',
  hover: {
    background: {
      color: 'background-contrast',
    },
    color: undefined,
  },
  size: {
    small: {
      border: {
        radius: 3px,
        width: 2px,
      },
      pad: {
        vertical: 4px,
        horizontal: 4px,
      },
      font: 14px,
      height: 30px,
      width: 30px,
    },
    medium: {
      border: {
        radius: 4px,
        width: 2px,
      },
      pad: {
        vertical: 4px,
        horizontal: 4px,
      },
      font: 18px,
      height: 36px,
      width: 36px,
    },
    large: {
      border: {
        radius: 6px,
        width: 2px,
      },
      pad: {
        vertical: 4px,
        horizontal: 4px,
      },
      font: 22px,
      height: 48px,
      width: 48px,
    },
  },
}

pagination.container

Any valid Box props for the Box wrapping the pagination controls.

object

{}

pagination.container.extend

Any additional style for the Box wrapping the pagination controls.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

pagination.controls.align

How the pagination controls should be aligned within the containing Box.

string

"center"

pagination.controls.direction

Direction in which the containing Box should display the pagination controls.

string

"row"

pagination.controls.gap

Amount of gap spacing between each control.

string

"xxsmall"

pagination.controls.margin

Amount of margin surrounding the controls.

string

"none"

pagination.controls.pad

Amount of pad surrounding the controls.

string

"none"

pagination.icons.color

The color used for the icon.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

pagination.icons.next

Icon to use as the 'next page' control.

element

<Next />

pagination.icons.previous

Icon to use as the 'previous page' control.

element

<Previous />