index.mdx

title	Pagination
description	Use Pagination to display a sequence of links that allow navigation to discrete, related pages.
keywords	page numbers page navigation
show-tabs	false
ready	true
source	https://github.com/primer/brand/blob/main/packages/react/src/Pagination/Pagination.tsx
storybook	/brand/storybook/?path=/story/components-pagination--playground
thumbnail	/images/thumbnails/pagination-thumbnail.png
thumbnail_darkMode	/images/thumbnails/pagination-thumbnail-dark.png

import {Label} from '@primer/react'

import {Pagination} from '@primer/react-brand'

Examples

Default

const App = () => {
  const [currentPage, setCurrentPage] = React.useState(5)
  const totalPages = 10

  const handlePageChange = (e, pageNumber) => {
    if (pageNumber === currentPage + 1 && currentPage < totalPages) {
      // Next page handler
      setCurrentPage(currentPage + 1)
    } else if (pageNumber === currentPage - 1 && currentPage > 1) {
      // Previous page handler
      setCurrentPage(currentPage - 1)
    } else if (pageNumber >= 1 && pageNumber <= totalPages) {
      setCurrentPage(pageNumber)
    }
  }

  return <Pagination pageCount={10} currentPage={currentPage} onPageChange={handlePageChange} />
}

render(<App />)

Hide page numbers

<Pagination pageCount={15} currentPage={5} showPages={false} />

Custom href

<Pagination pageCount={3} currentPage={1} hrefBuilder={n => `https://primer.style/brand/page/${n}`} />

Custom data attributes

<Pagination
  pageCount={3}
  currentPage={1}
  pageAttributesBuilder={n => {
    return {
      'data-custom-attribute': `custom-attribute-${n}`,
    }
  }}
/>

Custom button labels

Use the labels prop to customize the visible text of the previous and next controls. When localizing content, remember to also set the matching prevAriaLabel and nextAriaLabel labels so that the accessible names stay in sync with the visible text.

<Pagination
  pageCount={3}
  currentPage={2}
  labels={{
    prev: 'Précédent',
    next: 'Suivant',
    prevAriaLabel: 'Page précédente',
    nextAriaLabel: 'Page suivante',
  }}
/>

Component props

Pagination Required

name	type	default	required	description
pageCount	number		true	The total number of pages
currentPage	number		true	The current page number
onPageChange	(e: React.MouseEvent, n: number) => void		false	Callback function for when the page changes
hrefBuilder	(n: number) => string		false	Function to build the href for each page
pageAttributesBuilder	(n: number, page: PaginationPageType) => {[attributeName: string]: string}		false	Forward custom attributes to pagination items.
marginPageCount	number		false	Defines how many pages are to be displayed on the left and right of the component. Will be reduced on narrow viewports.
showPages	boolean		false	Whether to show the page numbers
surroundingPageCount	number		false	The number of pages to show on each side of the current page. Will be hidden on narrow viewports.
labels	{prev?: string; next?: string; prevAriaLabel?: string; nextAriaLabel?: string}		false	Custom text and accessible labels for the previous and next controls. Provide any subset.