Pagination | Park UI

Installation

npx @park-ui/cli@next add pagination

Add Component

Copy the code snippet below into you components folder.

'use client'
import { Pagination, usePaginationContext } from '@ark-ui/react/pagination'
import { EllipsisIcon } from 'lucide-react'
import type { ComponentProps } from 'react'
import { createStyleContext } from 'styled-system/jsx'
import { pagination } from 'styled-system/recipes'
import { IconButton } from './icon-button'

const { withProvider, withContext } = createStyleContext(pagination)

export type RootProps = ComponentProps<typeof Root>
export const Root = withProvider(Pagination.Root, 'root')
export const RootProvider = withProvider(Pagination.RootProvider, 'root')
export const Item = withContext(Pagination.Item, 'item')
export const Ellipsis = withContext(Pagination.Ellipsis, 'ellipsis')
export const PrevTrigger = withContext(Pagination.PrevTrigger, 'prevTrigger')
export const NextTrigger = withContext(Pagination.NextTrigger, 'nextTrigger')

export { PaginationContext as Context } from '@ark-ui/react/pagination'

export interface PaginationItemsProps extends React.HTMLAttributes<HTMLElement> {
  render: (page: { type: 'page'; value: number; selected: boolean }) => React.ReactNode
  ellipsis?: React.ReactElement | undefined
}

export const Items = (props: PaginationItemsProps) => {
  const ctx = usePaginationContext()
  const { render, ellipsis, ...rest } = props

  return ctx.pages.map((page, index) => {
    if (page.type === 'ellipsis') {
      return (
        <Ellipsis asChild key={index} index={index} {...rest}>
          {ellipsis || (
            <IconButton as="span" colorPalette="gray">
              <EllipsisIcon />
            </IconButton>
          )}
        </Ellipsis>
      )
    }

    return (
      <Item asChild key={index} type="page" value={page.value} {...rest}>
        {render({ ...page, selected: ctx.page === page.value })}
      </Item>
    )
  })
}

Integrate Recipe

Integrate this recipe in to your Panda config.

import { paginationAnatomy } from '@ark-ui/react/pagination'
import { defineSlotRecipe } from '@pandacss/dev'

export const pagination = defineSlotRecipe({
  className: 'pagination',
  slots: paginationAnatomy.keys(),
  base: {},
})

Usage

import { Pagination } from '@/components/ui'

<Pagination.Root>
  <Pagination.PrevTrigger />
  <Pagination.Ellipsis />
  <Pagination.Item />
  <Pagination.PageText />
  <Pagination.NextTrigger />
</Pagination.Root>

Shortcuts

The Pagination component also provides a set of shortcuts for common use cases.

PaginationItems

This component renders the number of pages based on the count and pageSize props. Rendering this:

<Pagination.Items />

is shorthand for this:

<Pagination.Context>
  {({ pages }) =>
    pages.map((page, index) =>
      page.type === "page" ? (
        <Pagination.Item key={index} {...page} />
      ) : (
        <Pagination.Ellipsis key={index} index={index} />
      ),
    )
  }
</Pagination.Context>

Props

Root

Prop	Default	Type
`defaultPage`	`1`	`number` The initial active page when rendered. Use when you don't need to control the active page of the pagination.
`defaultPageSize`	`10`	`number` The initial number of data items per page when rendered. Use when you don't need to control the page size of the pagination.
`siblingCount`	`1`	`number` Number of pages to show beside active page
`type`	`\button\`	`'button' \| 'link'` The type of the trigger element
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior.
`count`		`number` Total number of data items
`getPageUrl`		`(details: PageUrlDetails) => string` Function to generate href attributes for pagination links. Only used when `type` is set to "link".
`ids`		`Partial<{ root: string ellipsis: (index: number) => string prevTrigger: string nextTrigger: string item: (page: number) => string }>` The ids of the elements in the accordion. Useful for composition.
`onPageChange`		`(details: PageChangeDetails) => void` Called when the page number is changed
`onPageSizeChange`		`(details: PageSizeChangeDetails) => void` Called when the page size is changed
`page`		`number` The controlled active page
`pageSize`		`number` The controlled number of data items per page
`translations`		`IntlTranslations` Specifies the localized strings that identifies the accessibility elements and their states

Ellipsis

Prop	Default	Type
`index`*		`number`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior.

Item

Prop	Default	Type
`type`*		`'page'`
`value`*		`number`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior.