Pagination API

Import

import { Pagination } from '@cimpress-ui/react';

Controlled/uncontrolled usage

This component can be used in a controlled or uncontrolled way.

In the controlled way, this component doesn’t maintain its own internal state, and its value is provided by the parent component. Use the controlled way when you need to be able to change the state of this component in other parts of your application.

In the uncontrolled way, this component maintains its own internal state, and can optionally notify the parent component when its internal state changes. Use the uncontrolled way when you don’t need to change the state of this component in other parts of your application.

Preview
Code

Controlled

Uncontrolled

import { Pagination, Stack, Text } from '@cimpress-ui/react';
import { useState } from 'react';

export default function Demo() {
  const [currentPage, setCurrentPage] = useState(3);

  return (
    <Stack gap={32}>
      <Stack gap={16}>
        <Text as="h2" variant="title-4">
          Controlled
        </Text>

        <Pagination aria-label="Pagination" pageCount={10} currentPage={currentPage} onPageChange={setCurrentPage} />
      </Stack>

      <Stack gap={16}>
        <Text as="h2" variant="title-4">
          Uncontrolled
        </Text>

        <Pagination aria-label="Pagination" pageCount={10} defaultPage={3} />
      </Stack>
    </Stack>
  );
}

Accessibility notes

Pagination renders a navigation landmark, and requires a textual label to identify itself to assistive technologies. See our accessibility guide for more details.

If pagination controls a subsection of the page (for example, a data table), paginatedElementId prop should be set to the id of the paginated element. This allows assistive technologies to understand the association between the paginated element and its pagination controls.

API reference

Pagination

Allows navigating across multiple pages of related content.

See pagination usage guidelines.

ref Section titled “ ref ” Ref<HTMLElement>: The ref type for this component.

PaginationProps

pageCount * Section titled “ pageCount * ” number: The total number of pages.
paginatedElementId Section titled “ paginatedElementId ” string: The id of the paginated element. You must provide this prop when pagination controls a subsection of the page (for example, a data table).
currentPage Section titled “ currentPage ” number: The current page number (controlled). Should be between 1 and pageCount.
defaultPage Section titled “ defaultPage ” number: The default page number (uncontrolled). Should be between 1 and pageCount.
onPageChange Section titled “ onPageChange ” (page: number) => void: A callback function that is called when the page number changes.
href Section titled “ href ” (page: number) => string: A function that returns a URL for a given page number.
id Section titled “ id ” string: The element's unique identifier. See MDN.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
aria-label Section titled “ aria-label ” string: Defines a string value that labels the current element.
aria-labelledby Section titled “ aria-labelledby ” string: Identifies the element (or elements) that labels the current element.
aria-describedby Section titled “ aria-describedby ” string: Identifies the element (or elements) that describes the object.
aria-details Section titled “ aria-details ” string: Identifies the element (or elements) that provide a detailed, extended description for the object.
routerOptions Section titled “ routerOptions ” undefined: Options for the configured client side router.
hrefLang Section titled “ hrefLang ” string: Hints at the human language of the linked URL. SeeMDN.
target Section titled “ target ” HTMLAttributeAnchorTarget: The target window for the link. See MDN.
rel Section titled “ rel ” string: The relationship between the linked resource and the current page. See MDN.
download Section titled “ download ” string | boolean: Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.
ping Section titled “ ping ” string: A space-separated list of URLs to ping when the link is followed. See MDN.
referrerPolicy Section titled “ referrerPolicy ” HTMLAttributeReferrerPolicy: How much of the referrer to send when following the link. See MDN.

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

Pagination API

Import

Controlled/uncontrolled usage

Controlled

Uncontrolled

Accessibility notes

API reference

Pagination

ref

pageCount *

paginatedElementId

currentPage

defaultPage

onPageChange

href

id

data-cim-style-root

UNSAFE_className

UNSAFE_style

aria-label

aria-labelledby

aria-describedby

aria-details

routerOptions

hrefLang

target

rel

download

ping

referrerPolicy

margin

marginX

marginY

marginTop

marginRight

marginBottom

marginLeft