QUI React2.6.3

Pagination

The Pagination component enables the user to select a specific page from a range of pages.

import {QPagination} from "@qui/react"

Examples

Showcase

import {ReactNode} from "react"


import {QPagination} from "@qui/react"


export default function Showcase(): ReactNode {
  return <QPagination rowsPerPage={10} totalRows={120} />
}

Customization

Provide the rowsPerPageOptions prop to render a dropdown that allows users to select the number of rows per page. Show metadata about the current and total pages with the renderPageMeta prop. For more detailed documentation, refer to the API section.

1 of 12
10
import {ReactNode} from "react"


import {QPagination} from "@qui/react"


export default function Customization(): ReactNode {
  return (
    <QPagination
      defaultRowsPerPage={10}
      renderPageMeta={({currentPage, totalPages}) =>
        `${currentPage} of ${totalPages}`
      }
      rowsPerPageOptions={[10, 20, 50, 100]}
      totalRows={120}
    />
  )
}

Ranges

You can specify how many links to display on either side of the current page with the siblingCount prop. Use the boundaryCount property to adjust the number of pages that are always visible at the start and end.

import {ReactNode} from "react"


import {QPagination} from "@qui/react"


export default function Ranges(): ReactNode {
  return (
    <div className="grid justify-center gap-4">
      <QPagination defaultPage={6} siblingCount={0} totalRows={12} />


      {/* Default */}
      <QPagination defaultPage={6} totalRows={12} />


      <QPagination
        boundaryCount={2}
        defaultPage={6}
        siblingCount={0}
        totalRows={12}
      />


      <QPagination defaultPage={6} siblingCount={2} totalRows={120} />
    </div>
  )
}

Controlled

You can control the page and rowsPerPage. When you supply the onChange and page props, the component's page is controlled. When you supply the rowsPerPage and onRowsPerPageChange, the component's rows per page is controlled.

When the component is controlled, the state you pass in is the single source of truth. Any changes to the component's state must be made through the state passed in as props.

Refer to the corresponding documentation for a detailed explanation.

10
import {ReactNode, useState} from "react"


import {RotateCw} from "lucide-react"


import {QButton, QPagination} from "@qui/react"


export default function Controlled(): ReactNode {
  const [rowsPerPage, setRowsPerPage] = useState<number>(10)
  const [page, setPage] = useState(1)


  return (
    <div className="flex flex-col gap-4">
      <QPagination
        onChange={(nextValue, details) => {
          console.debug(details)
          setPage(nextValue)
        }}
        onRowsPerPageChange={(nextValue, details) => {
          console.debug(details)
          setRowsPerPage(nextValue)
        }}
        page={page}
        rowsPerPage={rowsPerPage}
        rowsPerPageOptions={[10, 20, 50, 100]}
        totalRows={120}
      />
      <div className="flex flex-col items-center gap-3">
        <QButton
          onClick={() => setPage(1)}
          size="s"
          startIcon={RotateCw}
          variant="outline"
        >
          Reset Page
        </QButton>
        <QButton
          onClick={() => setRowsPerPage(10)}
          size="s"
          startIcon={RotateCw}
          variant="outline"
        >
          Reset Rows Per Page
        </QButton>
      </div>
    </div>
  )
}

Playground

Options
Metadata
Rows Per Page Placement
1
TSX
<QPagination
  boundaryCount={1}
  hideNextButton={false}
  hidePageLinks={false}
  hidePrevButton={false}
  defaultPage={6}
  pageMetadataPlacement="before"
  rowsPerPagePlacement="after"
  siblingCount={1}
  totalRows={120}
/>

API

Props

Name & DescriptionOption(s)Default
totalRows
*
The total number of records.
number
1
as
The component used for the root node. It can be a React component or element.
| ElementType
| ComponentType
'div'
boundaryCount
Number of always visible pages at the beginning and end.
number
1
className
The className property of the Element interface gets and sets the value of the class attribute of the specified element.
string
defaultPage
The page selected by default.
number
1
defaultRowsPerPage
The default number of rows to show per page.
number
1
fullWidth
If true, the component will take up the full width of its parent container.
boolean
false
hideNextButton
If true, the next-page button will be hidden.
boolean
false
hidePageLinks
If true, the next-page button will be hidden.
boolean
hidePrevButton
If true, the previous-page button will be hidden.
boolean
false
nextPageAriaLabel
aria-label for the next-page button
string
'Go to next page'
onChange
Callback fired when the page value changes.
  • pageThe next value.
  • detailsThe details about the page change.
    (
      page: number,
      details: {
        event:
          | SyntheticEvent
          | KeyboardEvent<Element>
          | MouseEvent
        firstVisiblePage: number
        reason:
          | 'input'
          | 'reset'
          | 'rows-per-page-changed'
        totalPages: number
      },
    ) => void
    onRowsPerPageChange
    Callback fired when the rowsPerPage value changes.
    • rowsPerPageThe next value.
    • detailsThe details about the page change.
      (
        rowsPerPage: number,
        details: {
          event:
            | SyntheticEvent
            | KeyboardEvent<Element>
            | MouseEvent
          reason:
            | 'clear'
            | 'selectOption'
            | 'removeOption'
            | 'input'
            | 'reset'
        },
      ) => void
      page
      The current page (controlled).
      number
      pageAriaLabel
      Override the default aria-label for each page button.
          (
            page: number,
          ) => string
          		(page: number) =>
          pageMetadataPlacement
          Placement of the pageMetadata relative to the page links.
          | 'before'
          | 'after'
          'before'
          prevPageAriaLabel
          aria-label for the prev-page button
          string
          'Go to previous page'
          renderPageMeta
          A render function used to customize the current page report.
          • contextThe context derived from the current pagination state.
            (context: {
              currentPage: number
              totalPages: number
            }) => ReactNode | ReactElement
            rowsPerPage
            The number of rows to show per page.
            number
            1
            rowsPerPageLabel
            Label to show alongside the rows per page dropdown.
            | ReactNode
            | ReactElement
            rowsPerPageOptions
            Array of values for rows per page.
            number[]
            rowsPerPagePlacement
            Rows per page menu placement relative to the page links.
            | 'before'
            | 'after'
            'after'
            siblingCount
            Number of always visible pages before and after the current page.
            number
            1
            style
            The style global attribute contains CSS styling declarations to be applied to the element.
            CSSProperties
            Type
            number
            Default
            1
            Description
            The total number of records.
            Type
            | ElementType
            | ComponentType
            Default
            'div'
            Description
            The component used for the root node. It can be a React component or element.
            Type
            number
            Default
            1
            Description
            Number of always visible pages at the beginning and end.
            Type
            string
            Description
            The className property of the Element interface gets and sets the value of the class attribute of the specified element.
            Type
            number
            Default
            1
            Description
            The page selected by default.
            Type
            number
            Default
            1
            Description
            The default number of rows to show per page.
            Type
            boolean
            Default
            false
            Description
            If true, the component will take up the full width of its parent container.
            Type
            boolean
            Default
            false
            Description
            If true, the next-page button will be hidden.
            Type
            boolean
            Description
            If true, the next-page button will be hidden.
            Type
            boolean
            Default
            false
            Description
            If true, the previous-page button will be hidden.
            Type
            string
            Default
            'Go to next page'
            Description
            aria-label for the next-page button
            Type
            (
              page: number,
              details: {
                event:
                  | SyntheticEvent
                  | KeyboardEvent<Element>
                  | MouseEvent
                firstVisiblePage: number
                reason:
                  | 'input'
                  | 'reset'
                  | 'rows-per-page-changed'
                totalPages: number
              },
            ) => void
            Description
            Callback fired when the page value changes.
            • pageThe next value.
            • detailsThe details about the page change.
              Type
              (
                rowsPerPage: number,
                details: {
                  event:
                    | SyntheticEvent
                    | KeyboardEvent<Element>
                    | MouseEvent
                  reason:
                    | 'clear'
                    | 'selectOption'
                    | 'removeOption'
                    | 'input'
                    | 'reset'
                },
              ) => void
              Description
              Callback fired when the rowsPerPage value changes.
              • rowsPerPageThe next value.
              • detailsThe details about the page change.
                page
                Type
                number
                Description
                The current page (controlled).
                Type
                (
                  page: number,
                ) => string
                Default
                (page: number) =>
                Description
                Override the default aria-label for each page button.
                    Type
                    | 'before'
                    | 'after'
                    Default
                    'before'
                    Description
                    Placement of the pageMetadata relative to the page links.
                    Type
                    string
                    Default
                    'Go to previous page'
                    Description
                    aria-label for the prev-page button
                    Type
                    (context: {
                      currentPage: number
                      totalPages: number
                    }) => ReactNode | ReactElement
                    Description
                    A render function used to customize the current page report.
                    • contextThe context derived from the current pagination state.
                      Type
                      number
                      Default
                      1
                      Description
                      The number of rows to show per page.
                      Type
                      | ReactNode
                      | ReactElement
                      Description
                      Label to show alongside the rows per page dropdown.
                      Type
                      number[]
                      Description
                      Array of values for rows per page.
                      Type
                      | 'before'
                      | 'after'
                      Default
                      'after'
                      Description
                      Rows per page menu placement relative to the page links.
                      Type
                      number
                      Default
                      1
                      Description
                      Number of always visible pages before and after the current page.
                      Type
                      CSSProperties
                      Description
                      The style global attribute contains CSS styling declarations to be applied to the element.
                      Previous
                      Overlay Panel
                      Next
                      Popover
                      Examples
                      Showcase
                      Customization
                      Ranges
                      Controlled
                      Playground
                      API
                      Props
                      Copyright © 2025 QUALCOMM incorporated. All rights reserved. This site is built using QUI Docs. Head over to the template repository to start building.