Pagination

Pagination provides a control for moving through large, segmented content sets by exposing page numbers, previous and next actions, and optional overflow points when space is limited.

import {Pagination} from "@qualcomm-ui/react/pagination"

Examples

Showcase

The component renders the number of pages based on the count and pageSize props.

Brand

<Pagination.Root count={120} pageSize={10}>
  <Pagination.PageButtons />
</Pagination.Root>

Sizes

Customize the size of the component and its elements using the size prop.

Brand

import type {ReactElement} from "react"

import {Pagination} from "@qualcomm-ui/react/pagination"

export function PaginationSizesDemo(): ReactElement {
  return (
    <div className="flex flex-col gap-4">
      <Pagination.Root count={120} defaultPageSize={10} size="sm">
        <Pagination.PageButtons />
        <Pagination.PageSize options={[10, 20, 50, 100]}>
          <Pagination.PageSizeLabel>Page size</Pagination.PageSizeLabel>
        </Pagination.PageSize>
      </Pagination.Root>

      <Pagination.Root count={120} defaultPageSize={10} size="md">
        <Pagination.PageButtons />
        <Pagination.PageSize options={[10, 20, 50, 100]}>
          <Pagination.PageSizeLabel>Page size</Pagination.PageSizeLabel>
        </Pagination.PageSize>
      </Pagination.Root>
    </div>
  )
}

Page Size

Render a dropdown via <Pagination.PageSize> to adjust the number of data items per page.

Brand

<Pagination.Root count={120} defaultPageSize={10}>
  <Pagination.PageButtons />
  <Pagination.PageSize options={[10, 20, 50, 100]}>
    <Pagination.PageSizeLabel>Page size</Pagination.PageSizeLabel>
  </Pagination.PageSize>
</Pagination.Root>

Page Metadata

Show metadata about the current and total pages with <Pagination.PageMetadata>

To customize the text, supply children as a render prop.

Brand

Default

Customized

import type {ReactElement} from "react"

import {Pagination} from "@qualcomm-ui/react/pagination"

export function PaginationMetadataDemo(): ReactElement {
  return (
    <div className="flex flex-col">
      <div className="text-neutral-primary font-heading-xxs mb-2">Default</div>
      <Pagination.Root count={115} pageSize={10}>
        <Pagination.PageMetadata />
        <Pagination.PageButtons />
      </Pagination.Root>

      <div className="text-neutral-primary font-heading-xxs mt-4 mb-2">
        Customized
      </div>
      <Pagination.Root count={115} pageSize={10}>
        <Pagination.PageMetadata>
          {({count, page, pageCount, pageEnd, pageStart}) => (
            <div className="flex gap-2">
              <span>
                {pageStart}-{pageEnd} of {count}
              </span>
              <span>
                (page {page} of {pageCount})
              </span>
            </div>
          )}
        </Pagination.PageMetadata>
        <Pagination.PageButtons />
      </Pagination.Root>
    </div>
  )
}

Ranges

Brand

import type {ReactElement} from "react"

import {Pagination} from "@qualcomm-ui/react/pagination"

export function PaginationRangesDemo(): ReactElement {
  return (
    <div className="grid justify-center gap-4">
      <Pagination.Root count={12} defaultPage={6} siblingCount={0}>
        <Pagination.PageButtons />
      </Pagination.Root>

      {/* Default */}
      <Pagination.Root count={12} defaultPage={6}>
        <Pagination.PageButtons />
      </Pagination.Root>

      <Pagination.Root count={12} defaultPage={6} siblingCount={2}>
        <Pagination.PageButtons />
      </Pagination.Root>
    </div>
  )
}

Controlled State

The Pagination component follows our controlled state pattern for its page and pageSize props.

By default, the component is uncontrolled and manages these values internally. You may optionally control the current page or page size by supplying the properties and their corresponding onChange functions:

Brand

import {type ReactElement, useState} from "react"

import {Pagination} from "@qualcomm-ui/react/pagination"

export function PaginationControlledStateDemo(): ReactElement {
  const [page, setPage] = useState(1)
  const [pageSize, setPageSize] = useState(10)

  return (
    <Pagination.Root
      count={100}
      onPageChange={(pageValue) => setPage(pageValue)}
      onPageSizeChange={(pageSizeValue) => {
        setPageSize(pageSizeValue)
      }}
      page={page}
      pageSize={pageSize}
    >
      <Pagination.PageSize options={[5, 10, 25, 50]}>
        <Pagination.PageSizeLabel>Items per page:</Pagination.PageSizeLabel>
      </Pagination.PageSize>

      <Pagination.PageButtons />

      <Pagination.PageMetadata>
        {({count, pageEnd, pageStart}) => (
          <span>
            Showing {pageStart}-{pageEnd} of {count} items
          </span>
        )}
      </Pagination.PageMetadata>
    </Pagination.Root>
  )
}

Shortcuts

Shortcuts enable quick implementations for common use cases.

PageItems

Rendering <Pagination.PageItems /> is shorthand for this:

<PaginationContext>
  {(context) => (
    <>
      {context.pageItems.map((item, index) => {
        const itemProps = context.getPageItemProps(item)
        return <Pagination.PageItem key={index} {...itemProps} />
      })}
      {children}
    </>
  )}
</PaginationContext>

PageSize

The <Pagination.PageSize /> shortcut is a convenient dropdown for selecting the number of items per page. It's shorthand for this:

<PolymorphicElement as="div" {...mergedProps}>
  {children}
  <Menu.Root
    onSelect={(value) => {
      setPageSize(parseInt(value))
    }}
    size={qdsContext.size}
  >
    <Menu.Trigger>
      <Menu.Button
        aria-labelledby={pageSizeLabelId}
        emphasis="neutral"
        size={qdsContext.size}
        variant="outline"
      >
        {pageSize}
      </Menu.Button>
    </Menu.Trigger>
    <Portal>
      <Menu.Positioner>
        <Menu.Content>
          {options.map((opt) => (
            <Menu.Item key={opt} value={`${opt}`}>
              {opt}
            </Menu.Item>
          ))}
        </Menu.Content>
      </Menu.Positioner>
    </Portal>
  </Menu.Root>
</PolymorphicElement>

PageButtons

The <Pagination.PageButtons> shortcut renders the prev, next, and individual page buttons:

<ActionGroup {...props}>
  <Pagination.PrevTrigger />
  <Pagination.PageItems />
  <Pagination.NextTrigger />
</ActionGroup>

API

PageMetadata

Metadata about the current page is available as a render prop from the <Pagination.PageMetadata> element:

<Pagination.PageMetadata>
  {({count, page, pageCount, pageEnd, pageStart}) => {
    // ...
  }}
</Pagination.PageMetadata>

Defines the available placeholders for pagination metadata templates.

Prop	Type
count The total number of data items across all pages.	number
page The currently active page number.	number
pageCount The total number of pages available.	number
pageEnd The 1-based index of the current page's last item.	number
pageStart The 1-based index of the current page's first item.	number

count

Type

number

Description

The total number of data items across all pages.

page

Type

number

Description

The currently active page number.

pageCount

Type

number

Description

The total number of pages available.

pageEnd

Type

number

Description

The 1-based index of the current page's last item.

pageStart

Type

number

Description

The 1-based index of the current page's first item.

<Pagination.Root>

Prop	Type	Default
children ^* React children prop.	ReactNode
count ^* The total number of data items.	number	1
boundaryCount Number of always visible pages at the beginning and end.	number	1
defaultPage The default active page.	number	1
defaultPageSize The default number of data items to show per page.	number	1
nextPageAriaLabel aria-label for the next-page button	string	'Go to next page'
onPageChange Callback fired when the page value changes.	( page: number, ) => void
onPageSizeChange Callback fired when the rowsPerPage value changes. pageSize:The next value.	( pageSize: number, ) => void
page The current page (controlled).	number
pageAriaLabel Override the default aria-label for each page button.	( page: number, ) => string	(page: number) =>
pageSize The number of rows to show per page.	number	1
prevPageAriaLabel aria-label for the prev-page button	string	'Go to previous page'
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
siblingCount Number of always visible pages before and after the current page.	number	1
size Governs the size and padding of pagination elements.	'sm' \| 'md'	'sm'

children

Type

ReactNode

Description

React children prop.

count

Type

number

Description

The total number of data items.

boundaryCount

Type

number

Description

Number of always visible pages at the beginning and end.

defaultPage

Type

number

Description

The default active page.

defaultPageSize

Type

number

Description

The default number of data items to show per page.

nextPageAriaLabel

Type

string

Description

aria-label for the next-page button

onPageChange

Type

(
  page: number,
) => void

Description

Callback fired when the page value changes.

onPageSizeChange

Type

(
  pageSize: number,
) => void

Description

Callback fired when the rowsPerPage value changes.

pageSize:The next value.

page

Type

number

Description

The current page (controlled).

pageAriaLabel

Type

(
  page: number,
) => string

Description

Override the default aria-label for each page button.

pageSize

Type

number

Description

The number of rows to show per page.

prevPageAriaLabel

Type

string

Description

aria-label for the prev-page button

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

siblingCount

Type

number

Description

Number of always visible pages before and after the current page.

size

Type

'sm' | 'md'

Description

Governs the size and padding of pagination elements.

<Pagination.PageSize>

Prop	Type
options ^* Available page sizes to choose from.	number[]
children React children prop.	ReactNode
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

options

Type

number[]

Description

Available page sizes to choose from.

children

Type

ReactNode

Description

React children prop.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

<Pagination.PageItems>

Prop	Type
children React children prop.	ReactNode
renderItem Page item Render Prop	BindingRenderProp<PaginationPageItemBindings>

children

Type

ReactNode

Description

React children prop.

renderItem

Type

BindingRenderProp<PaginationPageItemBindings>

Description

Page item Render Prop

Collapsible

Side Nav