﻿---
description: Компонент для навигации по страницам с поддержкой сложных сценариев отображения.
tags: search
---

# Pagination \[tag:component]

Компонент для навигации по страницам с поддержкой сложных сценариев отображения.
Особое внимание уделено цифровой доступности и гибкой кастомизации.

```jsx
<Pagination currentPage={5} totalPages={10} />
```

## Стиль кнопок навигации

Задается свойством `navigationButtonsStyle`:

```jsx
<Pagination navigationButtonsStyle="icon" currentPage={5} totalPages={10} />
<Pagination navigationButtonsStyle="caption" currentPage={5} totalPages={10} />
<Pagination navigationButtonsStyle="both" currentPage={5} totalPages={10} />
```

## Кастомизация элементов

С помощью свойств `renderPageButton` и `renderNavigationButton` можно отрисовать кастомные кнопки навигации и кнопки перехода по страницам.

* В `renderPageButton` прокидывается объект с пропсами типа `CustomPaginationPageButtonProps` - наследует API [`Tappable`](/components/tappable).
* в `renderNavigationButton` прокидывается объект с пропсами типа `CustomPaginationNavigationButton` наследует API [`Button`](/components/button).

В примере ниже мы задаём пользовательские кнопки навигации и даём возможность показать всплывающую подсказку
при наведении на конкретную страницу:

```jsx
const [currentPage, setCurrentPage] = React.useState(5);

return (
  <Pagination
    onChange={setCurrentPage}
    renderPageButton={(props) => (
      <Tooltip title={`Страница ${props['data-page']}`}>
        <Tappable {...props} />
      </Tooltip>
    )}
    renderNavigationButton={(props) => <Button {...props} mode="primary" />}
    currentPage={currentPage}
    totalPages={10}
  />
);
```

## Хук usePagination \[#use-pagination]

Для полного контроля над отображением используйте хук:

```jsx
const items = usePagination({
  totalPages: 10,
  currentPage: 5,
});

// items → [1, 'start-ellipsis', 4, 5, 6, 'end-ellipsis', 10]

return (
  <nav>
    {items.map((item) =>
      item === 'start-ellipsis' || item === 'end-ellipsis' ? (
        <span key={item}>...</span>
      ) : (
        <button key={item}>{item}</button>
      ),
    )}
  </nav>
);
```

### Когда использовать хук

* Нестандартный UI пагинации.
* Интеграция с кастомной логикой.
* Сложные анимации переходов.

## Доступность (a11y) \[#a11y]

Компонент использует `<nav role="navigation">` и связывает элементы через `aria-labelledby`,
поддерживая семантику навигации.

Дополнительно убедитесь, что:

* заданы уникальные метки, если на странице несколько компонентов:

  ```jsx
  // ❌ Плохо (дублирующиеся метки)
  <Pagination navigationLabel="Страницы" />
  <Pagination navigationLabel="Страницы" />

  // ✅ Хорошо
  <Pagination navigationLabel="Страницы статей" />
  <Pagination navigationLabel="Страницы комментариев" />
  ```

* в `navigationLabel` не используется слова "Навигация" или слова близких по значению,
  так как скринридер и так зачитывает это видя тег `nav` или `role="navigation"`.
  Лучше ограничиться чем-то вроде "Страницы".

## Свойства и методы \[#api]

### Pagination

| Свойство                   | Тип                                                                                                               | По умолчанию                     | Описание                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `boundaryCount`            | `number`                                                                                                          | `1`                              | Кол-во всегда видимых страниц в начале и в конце.                                                                                                                                                                                                                                                                                                                   |
| `currentPage`              | `number`                                                                                                          | `1`                              | Текущая страница.                                                                                                                                                                                                                                                                                                                                                   |
| `disabled`                 | `boolean`                                                                                                         | `-`                              | Блокировка взаимодействия с компонентом.                                                                                                                                                                                                                                                                                                                            |
| `getPageLabel`             | `((isCurrent: boolean) => string)`                                                                                | `-`                              | \[a11y] Функция для переопределения и/или локализации метки кнопки страницы.  > Note: По возможности лучше не использовать, так как компонент и так проставляет номер страницы в разметку, что достаточно для пользователей скринридеров. Дополнительная информация скорее будет избыточна, так как будет зачитываться для каждой кнопки при перемещении по списку. |
| `getRootRef`               | `Ref<HTMLElement>`                                                                                                | `-`                              |                                                                                                                                                                                                                                                                                                                                                                     |
| `navigationButtonsStyle`   | `"caption" \| "both" \| "icon"`                                                                                   | `icon`                           | Задаёт стиль отображения кнопок навигации.  - `icon` – показывать только иконку; - `caption` – показывать только подпись; - `both` – показывать и иконку, и подпись.                                                                                                                                                                                                |
| `navigationLabel`          | `string`                                                                                                          | `Страницы`                       | \[a11y] Метка для обозначения блока навигации.                                                                                                                                                                                                                                                                                                                      |
| `navigationLabelComponent` | `ElementType<any, keyof IntrinsicElements>`                                                                       | `h2`                             | Тип элемента отрисовки блока навигации.                                                                                                                                                                                                                                                                                                                             |
| `nextButtonCaption`        | `string`                                                                                                          | `Вперёд`                         | Декоративный текст для кнопки навигации вперёд.  > Note: Экранные дикторы будут использовать `nextButtonLabel`.                                                                                                                                                                                                                                                     |
| `nextButtonLabel`          | `string`                                                                                                          | `Перейти на следующую страницу`  | \[a11y] Метка для кнопки навигации вперёд.                                                                                                                                                                                                                                                                                                                          |
| `nextButtonTestId`         | `string`                                                                                                          | `-`                              | Передает атрибут `data-testid` для кнопки `next`.                                                                                                                                                                                                                                                                                                                   |
| `onChange`                 | `((page: number, event: MouseEvent<HTMLElement, MouseEvent>) => void)`                                            | `-`                              | Обработчик изменения выбранной страницы.                                                                                                                                                                                                                                                                                                                            |
| `pageButtonTestId`         | `((day: PaginationPageType, active: boolean) => string) \| undefined`                                             | `-`                              | Передает атрибут `data-testid` для кнопок страниц.                                                                                                                                                                                                                                                                                                                  |
| `prevButtonCaption`        | `string`                                                                                                          | `Назад`                          | Декоративный текст для кнопки навигации назад.  > Note: Экранные дикторы будут использовать `prevButtonLabel`.                                                                                                                                                                                                                                                      |
| `prevButtonLabel`          | `string`                                                                                                          | `Перейти на предыдущую страницу` | \[a11y] Метка для кнопки навигации назад.                                                                                                                                                                                                                                                                                                                           |
| `prevButtonTestId`         | `string`                                                                                                          | `-`                              | Передает атрибут `data-testid` для кнопки `prev`.                                                                                                                                                                                                                                                                                                                   |
| `ref`                      | `Ref<HTMLElement>`                                                                                                | `-`                              |                                                                                                                                                                                                                                                                                                                                                                     |
| `renderNavigationButton`   | `((props: ButtonProps & { 'data-page': number; 'data-testid': string \| undefined; }) => ReactNode) \| undefined` | `-`                              | Функция для кастомного рендера кнопок навигации `prev` и `next`.   > Note: `CustomPaginationNavigationButton` наследует API [Button](https://vkui.io/components/button).                                                                                                                                                                                            |
| `renderPageButton`         | `((props: TappableOmitProps & { 'data-page': number; }) => ReactNode)`                                            | `-`                              | Функция для кастомного рендера кнопок страниц.  > Note: `CustomPaginationPageButtonProps` наследует API [Tappable](https://vkui.io/components/tappable).                                                                                                                                                                                                            |
| `siblingCount`             | `number`                                                                                                          | `1`                              | Кол-во всегда видимых страниц по краям текущей страницы.                                                                                                                                                                                                                                                                                                            |
| `totalPages`               | `number`                                                                                                          | `1`                              | Общее кол-во страниц.                                                                                                                                                                                                                                                                                                                                               |

### usePagination

| Свойство        | Тип      | По умолчанию | Описание                                                 |
| --------------- | -------- | ------------ | -------------------------------------------------------- |
| `boundaryCount` | `number` | `1`          | Кол-во всегда видимых страниц в начале и в конце.        |
| `currentPage`   | `number` | `1`          | Текущая страница.                                        |
| `siblingCount`  | `number` | `1`          | Кол-во всегда видимых страниц по краям текущей страницы. |
| `totalPages`    | `number` | `1`          | Общее кол-во страниц.                                    |
