Pagination pages through homogeneous data — a list or a table. To switch between sections of the interface use CdsTabs, and to navigate the hierarchy of pages use CdsBreadcrumbs.

Anatomy

Pagination is a row of page buttons with arrows on the sides. The first and last page buttons appear with show-first-last-page, the quick jump field with quick-jumper, and the pages between the edges and the neighbors of the current one collapse into an ellipsis.

Storybook

Variations

Number of pages

The length prop sets the number of pages, v-model holds the number of the current one. While the focus is inside the pagination, the ← and → keys page through.

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>

Visible buttons

The total-visible prop limits how many buttons are visible at once — the remaining pages collapse into an ellipsis (its text is changed by the ellipsis prop). Without total-visible the component counts how many buttons fit into the container itself and collapses the extra ones.

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>

Edge pages

The show-first-last-page prop adds buttons that jump to the first and the last page. The only-first value keeps just the first page button — handy when the total number of pages is unknown or only approximate.

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 jump

The quick-jumper prop adds a field where the user types a page number and gets there on Enter or on blur. The label before the field is changed by the quick-jumper-label prop.

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 state

The disabled prop blocks the whole navigation — while the current page is loading, for example.

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>

Slots

Slots replace the default buttons while keeping the switching logic: every slot receives a ready onClick handler and the disabled state.

Slot	Description
item	A single page button; props carries everything to pass to it
first	Button that jumps to the first page
prev	Button that jumps to the previous page
next	Button that jumps to the next page
last	Button that jumps to the last page

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>

Guidelines

Storybook

Scenarios

Paged list

The classic pairing: the list shows the slice of data for the current page, the "Показано 1–4 из 23" caption gives a sense of the total, and total-visible="3" keeps the pagination compact next to the counter.

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>

Loading pages from the server

When the data comes from the server, watch v-model (or the first / prev / next / last / quickJump events) and fire the request on a page change. While the request is in flight, disabled blocks the pagination and guards against extra switches.

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>

Search with a page reset

Filtering recalculates the number of pages and resets the current page to the first one — otherwise the user may end up on a page that no longer exists. When the results fit on a single page, the pagination hides.

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

Props

Name	Type	Default	Description
activeColor	string | undefined	—	Color of the active page button
ariaLabel	string | undefined	'Навигация по страницам'	ARIA label of the root navigation element
color	string | undefined	—	Color of the page buttons
currentPageAriaLabel	string | undefined	'Текущая страница, страница {0}'	ARIA label of the current (active) page. {0} is replaced with the page number
disabled	boolean | null | undefined	null	Disabled state
ellipsis	string | undefined	'...'	Text displayed between pages when they are collapsed
firstAriaLabel	string | undefined	'Первая страница'	ARIA label of the first page button
firstIcon	IconValue | undefined	'first-page'	Icon of the first page button
lastAriaLabel	string | undefined	'Последняя страница'	ARIA label of the last page button
lastIcon	IconValue | undefined	'last-page'	Icon of the last page button
length	string | number | undefined	1	Number of pages
modelValue	number | undefined	(props) => props.start	The v-model value — the number of the current page
nextAriaLabel	string | undefined	'Следующая страница'	ARIA label of the next page button
nextIcon	IconValue | undefined	'chevron-right'	Icon of the next page button
pageAriaLabel	string | undefined	'Перейти к странице {0}'	ARIA label of a page button. {0} is replaced with the page number
prevIcon	IconValue | undefined	'chevron-left'	Icon of the previous page button
previousAriaLabel	string | undefined	'Предыдущая страница'	ARIA label of the previous page button
quickJumper	boolean | undefined	false	Shows the quick jump field
quickJumperLabel	string | undefined	'Перейти к странице'	Caption text before the quick jump field
showFirstLastPage	boolean | "only-first" | undefined	false	Shows the first/last page buttons. 'only-first' shows only the first page button
start	string | number | undefined	1	Initial page
tag	string | JSXComponent<any> | undefined	'nav'	Custom HTML tag or component to render
theme	string | undefined	—	Component theme
totalVisible	string | number | undefined	—	Number of page buttons visible at once

Events

Name	Type	Description
first	[value: number]	Fired on a jump to the first page
last	[value: number]	Fired on a jump to the last page
next	[value: number]	Fired on a jump to the next page
prev	[value: number]	Fired on a jump to the previous page
quickJump	[value: number]	Fired on a jump made through the quick jump field
update:modelValue	[value: number]	Fired when the v-model value changes

Slots

Name	Type	Description
first	CdsPaginationControlSlot	Slot of the first page button
item	CdsPaginationItemSlot	Slot of a single page button
last	CdsPaginationControlSlot	Slot of the last page button
next	CdsPaginationControlSlot	Slot of the next page button
prev	CdsPaginationControlSlot	Slot of the previous page button

Exposed

Name	Type	Description
setFirst	() => void	Jumps to the first page.
setLast	() => void	Jumps to the last page.
setNext	() => void	Jumps to the next page.
setPrev	() => void	Jumps to the previous page.