@zendeskgarden/react-pagination npm version

This package includes components relating to pagination in the Garden Design System.

Installation

npm install @zendeskgarden/react-pagination

# Peer Dependencies - Also Required
npm install react react-dom prop-types styled-components @zendeskgarden/react-theming

Usage

/**
 * Include pagination styling at the root of your application
 */
import '@zendeskgarden/react-pagination/dist/styles.css';

import { ThemeProvider } from '@zendeskgarden/react-theming';
import { Pagination } from '@zendeskgarden/react-pagination';

initialState = {
  currentPage: 1
};

/**
 * Place a `ThemeProvider` at the root of your React application
 */
<ThemeProvider>
  <Pagination totalPages={25} currentPage={state.currentPage} onStateChange={setState} />
</ThemeProvider>;

Elements

Pagination

import { Pagination } from '@zendeskgarden/react-pagination'
Prop name
Type
Default
Description
currentPage
number
Required

The currently selected page

totalPages
number
Required

The total number of pages available

focusedKey
union
-

The currently focused key

One of type: number, string
id
string
-

The root ID to use for descendants. A unique ID is created if none is provided.

onChange
func
-
Arguments
currentPage: Any — The newly selected page
onStateChange
func
-
Arguments
newState: Object
newState.focusedKey: Any — The newly focused page key
newState.currentPage: Any — The newly selected page
pagePadding
number
2

The number of pages to pad the currentPage with when determining the Gap placement

transformPageProps
func
-

Allows custom props to be applied to each page element. Useful for QA attributes and localization.

Arguments
pageType: String — Unique type for each page type: "previous", "page", "gap", and "next"
pageProps: Object — The props to be transformed for the page object

Default Usage

Custom Page Padding

Custom Page Props

There may be a need to apply custom styling, props, and QA attributes to each actionable page. This is possible with the transformPageProps prop. It provides the page type as well as the default props for you to modify.

Containers

PaginationContainer

import { PaginationContainer } from '@zendeskgarden/react-pagination'
Prop name
Type
Default
Description
children
func
-
Arguments
renderProps: Object
renderProps.getContainerProps: Function — Props to be spread onto the containing element
renderProps.getPageProps: Function — Props to be spread onto each page element. ({key}) is required. Use index attribute for custom ordering.
renderProps.getPreviousPageProps: Function — Props to be spread onto the previous page element. ({key}) is required.
renderProps.getNextPageProps: Function — Props to be spread onto the next page element. ({key}) is required.
renderProps.focusedKey: Any — Unique key of currently focused page
renderProps.selectedKey: Any — Unique key of currently selected page
focusedKey
union
-

The currently focused key

One of type: number, string
id
string
-

The root ID to use for descendants. A unique ID is created if none is provided. *

onStateChange
func
-
Arguments
newState: Object — The updated state
newState.selectedKey: Any — The newly selected key
newState.focusedKey: Any — The newly focused key
render
func
-

Identical to children

selectedKey
union
-

The currently selected key

One of type: number, string
vertical
unknown
false

DEPRECATION WARNING

This component has been deprecated in favor of the API provided in the @zendeskgarden/container-pagination package.

This component will be removed in a future major release.

<PaginationContainer>
  {({
    getContainerProps,
    getPageProps,
    getPreviousPageProps,
    getNextPageProps,
    focusedKey,
    selectedKey
  }) => (
    <PaginationView {...getContainerProps()}>
      <PreviousPage
        {...getPreviousPageProps({
          key: 'previous',
          focused: focusedKey === 'previous',
          current: selectedKey === 'previous'
        })}
      />
      <Page {...getPageProps({ key: 1, focused: focusedKey === 1, current: selectedKey === 1 })}>
        1
      </Page>
      <Page {...getPageProps({ key: 2, focused: focusedKey === 2, current: selectedKey === 2 })}>
        2
      </Page>
      <Page {...getPageProps({ key: 3, focused: focusedKey === 3, current: selectedKey === 3 })}>
        3
      </Page>
      <Page {...getPageProps({ key: 4, focused: focusedKey === 4, current: selectedKey === 4 })}>
        4
      </Page>
      <Page {...getPageProps({ key: 5, focused: focusedKey === 5, current: selectedKey === 5 })}>
        5
      </Page>
      <Page {...getPageProps({ key: 6, focused: focusedKey === 6, current: selectedKey === 6 })}>
        6
      </Page>
      <Page {...getPageProps({ key: 7, focused: focusedKey === 7, current: selectedKey === 7 })}>
        7
      </Page>
      <Gap />
      <Page {...getPageProps({ key: 25, focused: focusedKey === 25, current: selectedKey === 25 })}>
        25
      </Page>
      <NextPage
        {...getNextPageProps({
          key: 'next',
          focused: focusedKey === 'next',
          current: selectedKey === 'next'
        })}
      />
    </PaginationView>
  )}
</PaginationContainer>

Views

Gap

import { Gap } from '@zendeskgarden/react-pagination'

Accepts all <li> props

Prop name
Type
Default
Description
current
bool
-
focused
bool
-
hidden
bool
-
hovered
bool
-

NextPage

import { NextPage } from '@zendeskgarden/react-pagination'

Accepts all <li> props

Prop name
Type
Default
Description
current
bool
-
focused
bool
-
hidden
bool
-
hovered
bool
-

Page

import { Page } from '@zendeskgarden/react-pagination'

Accepts all <li> props

Prop name
Type
Default
Description
current
bool
-
focused
bool
-
hidden
bool
-
hovered
bool
-

PaginationView

import { PaginationView } from '@zendeskgarden/react-pagination'

Accepts all <ul> props

The PaginationView component is a logicless presentation component used to wrap Page and Gap components.

  • Previous
  • 1
  • 2
  • 3
  • 4
  • Next

PreviousPage

import { PreviousPage } from '@zendeskgarden/react-pagination'

Accepts all <li> props

Prop name
Type
Default
Description
current
bool
-
focused
bool
-
hidden
bool
-
hovered
bool
-