@primer/react-brand/docs/components/Pagination/index.md

Primer Brand is a GitHub's design system for creating React-based marketing websites and digital experiences.

---
title: Pagination
description: Use Pagination to display a sequence of links that allow navigation to discrete, related pages.
keywords: ['page numbers', 'page navigation']
ready: true
source: https://github.com/primer/brand/blob/main/packages/react/src/Pagination/Pagination.tsx
storybook: '/brand/storybook/?path=/story/components-pagination--playground'
---

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

## Examples

### Default

```jsx filename="noinline"
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

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

### Custom href

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

### Custom data attributes

```jsx
<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.

```jsx
<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.                               |