Пагинация листает однородные данные — список или таблицу. Для переключения между разделами интерфейса используйте CdsTabs, а для навигации по иерархии страниц — CdsBreadcrumbs.

Анатомия

Пагинация — ряд кнопок страниц со стрелками по краям. Кнопки первой и последней страницы появляются при show-first-last-page, поле быстрого перехода — при quick-jumper, а страницы между крайними и соседями текущей сворачиваются в многоточие.

Storybook

Вариации

Количество страниц

Свойство length задаёт количество страниц, v-model хранит номер текущей. Когда фокус внутри пагинации, страницы листаются клавишами ← и →.

Sandbox Storybook

<script setup lang="ts">
import { CdsPagination } from '@central-design-system/components';
import { ref } from 'vue';

const page = ref(1);
</script>

<template>
  <div class="flex justify-center">
    <CdsPagination v-model="page" length="10" />
  </div>
</template>

Видимые кнопки

Свойство total-visible ограничивает количество одновременно видимых кнопок — остальные страницы сворачиваются в многоточие (текст меняется свойством ellipsis). Без total-visible компонент сам считает, сколько кнопок помещается в контейнер, и сворачивает лишние.

Sandbox Storybook

<script setup lang="ts">
import { CdsPagination } from '@central-design-system/components';
import { ref } from 'vue';

const page = ref(5);
</script>

<template>
  <div class="flex justify-center">
    <CdsPagination v-model="page" length="20" total-visible="5" />
  </div>
</template>

Крайние страницы

Свойство show-first-last-page добавляет кнопки перехода к первой и последней странице. Значение only-first оставляет только кнопку первой страницы — удобно, когда общее число страниц неизвестно или считается приблизительно.

Sandbox Storybook

<script setup lang="ts">
import { CdsPagination } from '@central-design-system/components';
import { ref } from 'vue';

const page = ref(5);
const pageOnlyFirst = ref(5);
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsPagination v-model="page" length="10" total-visible="5" show-first-last-page />
    <CdsPagination v-model="pageOnlyFirst" length="10" total-visible="5" show-first-last-page="only-first" />
  </div>
</template>

Быстрый переход

Свойство quick-jumper добавляет поле, в котором пользователь вводит номер страницы и попадает на неё по Enter или по потере фокуса. Подпись перед полем меняется свойством quick-jumper-label.

Sandbox Storybook

<script setup lang="ts">
import { CdsPagination } from '@central-design-system/components';
import { ref } from 'vue';

const page = ref(1);
</script>

<template>
  <div class="flex justify-center">
    <CdsPagination v-model="page" length="20" total-visible="5" quick-jumper />
  </div>
</template>

Заблокированное состояние

Свойство disabled блокирует всю навигацию — например, пока грузится текущая страница.

Sandbox Storybook

<script setup lang="ts">
import { CdsPagination } from '@central-design-system/components';
import { ref } from 'vue';

const page = ref(3);
</script>

<template>
  <div class="flex justify-center">
    <CdsPagination v-model="page" length="10" disabled />
  </div>
</template>

Слоты

Слоты заменяют стандартные кнопки, сохраняя логику переключения: каждый слот получает готовый обработчик onClick и состояние disabled.

Слот	Описание
item	Кнопка отдельной страницы; в props — всё для передачи кнопке
first	Кнопка перехода на первую страницу
prev	Кнопка перехода на предыдущую страницу
next	Кнопка перехода на следующую страницу
last	Кнопка перехода на последнюю страницу

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsPagination } from '@central-design-system/components';
import { ref } from 'vue';

const page = ref(1);
</script>

<template>
  <div class="flex justify-center">
    <CdsPagination v-model="page" length="8" total-visible="5">
      <template #prev="{ onClick, disabled }">
        <CdsButton
          variant="soft"
          color="neutral"
          size="sm"
          prepend-icon="chevron-left"
          text="Назад"
          :disabled="disabled"
          @click="onClick"
        />
      </template>

      <template #next="{ onClick, disabled }">
        <CdsButton
          variant="soft"
          color="neutral"
          size="sm"
          append-icon="chevron-right"
          text="Вперёд"
          :disabled="disabled"
          @click="onClick"
        />
      </template>
    </CdsPagination>
  </div>
</template>

Рекомендации

Storybook

Сценарии использования

Список с постраничным выводом

Классическая связка: список показывает срез данных текущей страницы, подпись «Показано 1–4 из 23» ориентирует в общем объёме, а total-visible="3" держит пагинацию компактной рядом со счётчиком.

Sandbox Storybook

<script setup lang="ts">
import { CdsPagination } from '@central-design-system/components';
import { computed, ref } from 'vue';

const pageSize = 4;

const contracts = Array.from({ length: 23 }, (_, index) => ({
  id: index + 1,
  title: `Договор поставки №${1240 + index}`,
  date: `${String((index % 28) + 1).padStart(2, '0')}.06.2026`
}));

const page = ref(1);
const pages = Math.ceil(contracts.length / pageSize);

const visible = computed(() => contracts.slice((page.value - 1) * pageSize, page.value * pageSize));

const rangeLabel = computed(() => {
  const from = (page.value - 1) * pageSize + 1;
  const to = Math.min(page.value * pageSize, contracts.length);

  return `${from}–${to} из ${contracts.length}`;
});
</script>

<template>
  <div class="m-auto flex w-full max-w-md flex-col gap-3">
    <ul class="m-0 flex list-none flex-col gap-1 p-0">
      <li v-for="contract in visible" :key="contract.id" class="flex justify-between gap-3">
        <span>{{ contract.title }}</span>
        <span>{{ contract.date }}</span>
      </li>
    </ul>

    <div class="flex flex-wrap items-center justify-between gap-3">
      <span>Показано {{ rangeLabel }}</span>

      <CdsPagination v-model="page" :length="pages" total-visible="3" />
    </div>
  </div>
</template>

Загрузка страниц с сервера

Когда данные приходят с сервера, следите за v-model (или событиями first / prev / next / last / quickJump) и запускайте запрос при смене страницы. На время запроса disabled блокирует пагинацию и защищает от лишних переключений.

Sandbox Storybook

<script setup lang="ts">
import { CdsPagination, CdsProgressCircle } from '@central-design-system/components';
import { onMounted, ref, watch } from 'vue';

const pageSize = 3;
const total = 27;

const page = ref(1);
const loading = ref(false);
const items = ref<string[]>([]);

async function load() {
  loading.value = true;

  await new Promise((resolve) => setTimeout(resolve, 800));

  items.value = Array.from(
    { length: Math.min(pageSize, total - (page.value - 1) * pageSize) },
    (_, index) => `Заявка №${(page.value - 1) * pageSize + index + 1} — согласование договора`
  );

  loading.value = false;
}

watch(page, load);
onMounted(load);
</script>

<template>
  <div class="m-auto flex w-full max-w-md flex-col items-center gap-3">
    <div class="flex min-h-[72px] w-full items-center justify-center">
      <CdsProgressCircle v-if="loading" indeterminate aria-label="Загружаем страницу" />

      <ul v-else class="m-0 flex w-full list-none flex-col gap-1 p-0">
        <li v-for="item in items" :key="item">{{ item }}</li>
      </ul>
    </div>

    <CdsPagination v-model="page" :length="total / pageSize" total-visible="5" :disabled="loading" />
  </div>
</template>

Поиск со сбросом страницы

При фильтрации количество страниц пересчитывается, а текущая страница сбрасывается на первую — иначе пользователь может остаться на странице, которой больше нет. Когда результатов хватает на одну страницу, пагинация скрывается.

Sandbox Storybook

<script setup lang="ts">
import { CdsPagination, CdsTextInput } from '@central-design-system/components';
import { computed, ref, watch } from 'vue';

const pageSize = 4;

const companies = [
  'Альфа Логистика',
  'Вектор Строй',
  'Гранит Сервис',
  'Дельта Транс',
  'Звезда Ритейл',
  'Импульс Энерго',
  'Квант Технологии',
  'Ладога Снаб',
  'Меркурий Опт',
  'Нева Комплект',
  'Орион Металл',
  'Прогресс Авто',
  'Ресурс Групп',
  'Салют Пром',
  'Титан Инжиниринг',
  'Урал Механика',
  'Фотон Электро',
  'Эталон Сталь'
];

const query = ref('');
const page = ref(1);

const filtered = computed(() =>
  companies.filter((company) => company.toLowerCase().includes(query.value.trim().toLowerCase()))
);

const pages = computed(() => Math.ceil(filtered.value.length / pageSize));

const visible = computed(() => filtered.value.slice((page.value - 1) * pageSize, page.value * pageSize));

watch(query, () => (page.value = 1));
</script>

<template>
  <div class="m-auto flex w-full max-w-md flex-col gap-3">
    <CdsTextInput v-model="query" placeholder="Поиск по контрагентам" prepend-inner-icon="search" clearable />

    <ul class="m-0 flex list-none flex-col gap-1 p-0">
      <li v-for="company in visible" :key="company">{{ company }}</li>
      <li v-if="filtered.length === 0">Ничего не найдено</li>
    </ul>

    <div v-if="pages > 1" class="flex justify-center">
      <CdsPagination v-model="page" :length="pages" total-visible="5" />
    </div>
  </div>
</template>

API

Пропсы

Имя	Тип	По умолчанию	Описание
activeColor	string | undefined	—	Цвет активной кнопки страницы
ariaLabel	string | undefined	'Навигация по страницам'	ARIA-метка корневого элемента навигации
color	string | undefined	—	Цвет кнопок страниц
currentPageAriaLabel	string | undefined	'Текущая страница, страница {0}'	ARIA-метка текущей (активной) страницы. {0} заменяется номером страницы
disabled	boolean | null | undefined	null	Заблокированное состояние
ellipsis	string | undefined	'...'	Текст, отображаемый между страницами при их сокрытии
firstAriaLabel	string | undefined	'Первая страница'	ARIA-метка кнопки перехода на первую страницу
firstIcon	IconValue | undefined	'first-page'	Иконка кнопки перехода на первую страницу
lastAriaLabel	string | undefined	'Последняя страница'	ARIA-метка кнопки перехода на последнюю страницу
lastIcon	IconValue | undefined	'last-page'	Иконка кнопки перехода на последнюю страницу
length	string | number | undefined	1	Количество страниц
modelValue	number | undefined	(props) => props.start	Значение v-model — номер текущей страницы
nextAriaLabel	string | undefined	'Следующая страница'	ARIA-метка кнопки перехода на следующую страницу
nextIcon	IconValue | undefined	'chevron-right'	Иконка кнопки перехода на следующую страницу
pageAriaLabel	string | undefined	'Перейти к странице {0}'	ARIA-метка кнопки страницы. {0} заменяется номером страницы
prevIcon	IconValue | undefined	'chevron-left'	Иконка кнопки перехода на предыдущую страницу
previousAriaLabel	string | undefined	'Предыдущая страница'	ARIA-метка кнопки перехода на предыдущую страницу
quickJumper	boolean | undefined	false	Отображение поля быстрого перехода к странице
quickJumperLabel	string | undefined	'Перейти к странице'	Текст-подпись перед полем быстрого перехода к странице
showFirstLastPage	boolean | "only-first" | undefined	false	Отображение кнопок перехода на первую/последнюю страницу. 'only-first' — только на первую
start	string | number | undefined	1	Начальная страница
tag	string | JSXComponent<any> | undefined	'nav'	Пользовательский HTML-тег для отображения
theme	string | undefined	—	Тема компонента
totalVisible	string | number | undefined	—	Количество одновременно видимых кнопок страниц

События

Имя	Тип	Описание
first	[value: number]	Событие перехода на первую страницу
last	[value: number]	Событие перехода на последнюю страницу
next	[value: number]	Событие перехода на следующую страницу
prev	[value: number]	Событие перехода на предыдущую страницу
quickJump	[value: number]	Событие перехода с помощью поля быстрого перехода
update:modelValue	[value: number]	Событие изменения значения v-model

Слоты

Имя	Тип	Описание
first	CdsPaginationControlSlot	Слот кнопки перехода на первую страницу
item	CdsPaginationItemSlot	Слот кнопки отдельной страницы
last	CdsPaginationControlSlot	Слот кнопки перехода на последнюю страницу
next	CdsPaginationControlSlot	Слот кнопки перехода на следующую страницу
prev	CdsPaginationControlSlot	Слот кнопки перехода на предыдущую страницу

Exposed

Имя	Тип	Описание
setFirst	() => void	Переходит на первую страницу.
setLast	() => void	Переходит на последнюю страницу.
setNext	() => void	Переходит на следующую страницу.
setPrev	() => void	Переходит на предыдущую страницу.