The dropdowns of CdsSelect and CdsAutocomplete, as well as the CdsTree tree, already virtualize their items — there is no need to wrap them. Render a short list — up to a couple of hundred rows — with the regular CdsList: virtualization will not pay off there.

Variations

Fixed height

The height prop sets the height of the viewport — the scrolling happens inside it. If all the rows have the same height, set item-height: the component will not measure every row, and the positions and the scrollbar will be exact from the very first render.

Sandbox Storybook

<script setup lang="ts">
import { CdsCard, CdsList, CdsListItem, CdsVirtualScroll } from '@central-design-system/components';

const items = Array.from({ length: 10000 }, (_, index) => ({
  title: `Позиция каталога №${index + 1}`
}));
</script>

<template>
  <CdsCard class="m-auto w-[320px]">
    <CdsList>
      <CdsVirtualScroll height="300" item-height="36" :items="items">
        <template #default="{ item, index }">
          <CdsListItem
            :base-color="index % 2 ? 'surface-primary' : 'surface-secondary'"
            :height="36"
            :title="item.title"
          />
        </template>
      </CdsVirtualScroll>
    </CdsList>
  </CdsCard>
</template>

Dynamic height

Without item-height the component measures the rows automatically — this fits content of variable length: comments, messages, descriptions. The heights get refined as you scroll, so the scrollbar may shift slightly.

Sandbox Storybook

<script setup lang="ts">
import { CdsCard, CdsVirtualScroll } from '@central-design-system/components';

const texts = [
  'Согласовано.',
  'Уточните, пожалуйста, сроки поставки: в прошлой заявке отгрузка задержалась на неделю.',
  'Прошу приложить спецификацию к позиции.',
  'Цена выше средней по рынку — запросите у поставщика пересчёт и добавьте обоснование к заявке, иначе финансовый отдел вернёт её на доработку.'
];

const items = Array.from({ length: 5000 }, (_, index) => ({
  id: index + 1,
  author: `Участник ${(index % 27) + 1}`,
  text: texts[index % texts.length]
}));
</script>

<template>
  <CdsCard class="m-auto w-[360px]">
    <CdsVirtualScroll height="300" item-key="id" :items="items">
      <template #default="{ item }">
        <div class="border-b border-line-primary p-2">
          <div class="text-100 text-content-secondary">{{ item.author }}</div>
          <div class="text-200">{{ item.text }}</div>
        </div>
      </template>
    </CdsVirtualScroll>
  </CdsCard>
</template>

Renderless mode

The renderless prop removes the own scroll container: the component listens to the scrolling of the nearest scrollable parent and renders the rows without wrappers. The slot additionally receives itemRef — bind it to the root node of the row so that the component knows its height. This is how the list fits into an existing scroll — of a panel or of the whole page. Give the scrollable parent position: relative — the component counts the row positions from it.

Sandbox Storybook

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

const items = Array.from({ length: 3000 }, (_, index) => `Строка отчёта №${index + 1}`);
</script>

<template>
  <div class="relative m-auto h-[300px] w-[360px] overflow-y-auto rounded-200 border border-line-primary p-2">
    <div class="text-300">Отчёт за квартал</div>
    <p class="text-100 text-content-secondary">
      Шапка — часть общего потока: скролл-контейнер здесь один, родительский, и заголовок прокручивается вместе со
      строками списка.
    </p>

    <CdsVirtualScroll renderless :items="items">
      <template #default="{ item, itemRef }">
        <div :ref="itemRef" class="py-1">{{ item }}</div>
      </template>
    </CdsVirtualScroll>
  </div>
</template>

Guidelines

Storybook

Scenarios

Catalog search

Pass an already filtered array to items: a computed recalculates the records on input, and the component picks the new list up on its own. item-key="id" binds the rows to the records rather than to the positions in the array — so the rows do not get mixed up while filtering.

Sandbox Storybook

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

const query = ref('');

const categories = ['Крепёж', 'Инструмент', 'Электрика', 'Сантехника', 'Спецодежда'];

const items = Array.from({ length: 10000 }, (_, index) => ({
  id: index + 1,
  title: `${categories[index % categories.length]}, артикул ${10000 + index}`
}));

const filtered = computed(() => {
  const search = query.value.trim().toLowerCase();

  return search ? items.filter((item) => item.title.toLowerCase().includes(search)) : items;
});
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col gap-2">
    <CdsTextInput v-model="query" clearable hide-details placeholder="Поиск по каталогу" prepend-inner-icon="search" />

    <CdsCard>
      <CdsList v-if="filtered.length">
        <CdsVirtualScroll height="260" item-height="36" item-key="id" :items="filtered">
          <template #default="{ item }">
            <CdsListItem :height="36" :title="item.title" />
          </template>
        </CdsVirtualScroll>
      </CdsList>
      <div v-else class="p-2 text-content-secondary">Ничего не найдено</div>
    </CdsCard>

    <div class="text-100 text-content-secondary">Найдено: {{ filtered.length.toLocaleString('ru-RU') }}</div>
  </div>
</template>

Jumping through a journal

The component exposes the scrollToIndex method — get it through a ref and scroll the list programmatically. The month buttons calculate the index of the first operation of the month; with a fixed item-height the jump lands exactly on the right row.

Sandbox Storybook

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

const MONTHS = [
  'Январь',
  'Февраль',
  'Март',
  'Апрель',
  'Май',
  'Июнь',
  'Июль',
  'Август',
  'Сентябрь',
  'Октябрь',
  'Ноябрь',
  'Декабрь'
];
const PER_MONTH = 400;

const items = Array.from({ length: MONTHS.length * PER_MONTH }, (_, index) => ({
  id: index + 1,
  title: `${MONTHS[Math.floor(index / PER_MONTH)]} — операция №${index + 1}`
}));

const virtualScroll = ref<InstanceType<typeof CdsVirtualScroll>>();

function scrollToMonth(month: number) {
  virtualScroll.value?.scrollToIndex(month * PER_MONTH);
}
</script>

<template>
  <div class="m-auto flex w-[400px] flex-col gap-2">
    <div class="flex flex-wrap justify-center gap-1">
      <CdsButton
        v-for="(month, index) in MONTHS"
        :key="month"
        variant="soft"
        color="neutral"
        size="xs"
        @click="scrollToMonth(index)"
      >
        {{ month.slice(0, 3) }}
      </CdsButton>
    </div>

    <CdsCard>
      <CdsList>
        <CdsVirtualScroll ref="virtualScroll" height="260" item-height="36" item-key="id" :items="items">
          <template #default="{ item }">
            <CdsListItem :height="36" :title="item.title" />
          </template>
        </CdsVirtualScroll>
      </CdsList>
    </CdsCard>
  </div>
</template>

Selection in a long list

The rows outside the screen do not exist in the DOM, so keep the selection state in the data, not in the rows themselves. In the demo the checked ids live in a Set: the checkbox of a row reads it and changes it on click — the selection survives any scrolling.

Sandbox Storybook

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

const departments = ['Закупки', 'Продажи', 'Логистика', 'Финансы'];

const employees = Array.from({ length: 8000 }, (_, index) => ({
  id: index + 1,
  name: `Сотрудник ${index + 1}`,
  department: departments[index % departments.length]
}));

const selected = ref(new Set<number>());

function toggle(id: number) {
  if (selected.value.has(id)) {
    selected.value.delete(id);
  } else {
    selected.value.add(id);
  }
}
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col gap-2">
    <CdsCard>
      <CdsVirtualScroll height="260" item-height="40" item-key="id" :items="employees">
        <template #default="{ item }">
          <div class="flex h-[40px] items-center justify-between px-2">
            <CdsCheckbox
              hide-details
              :label="item.name"
              :model-value="selected.has(item.id)"
              @update:model-value="toggle(item.id)"
            />
            <span class="text-100 text-content-secondary">{{ item.department }}</span>
          </div>
        </template>
      </CdsVirtualScroll>
    </CdsCard>

    <div class="text-100 text-content-secondary">Выбрано получателей: {{ selected.size }}</div>
  </div>
</template>

API

CdsVirtualScroll

Props

Name	Type	Default	Description
height	string | number | undefined	—	Component height
itemHeight	string | number | undefined	null	Height of a single item in pixels. When omitted, the height is measured automatically.
itemKey	SelectItemKey	null	Key that identifies an item (a field name, a path or a function). The index is used by default.
items	readonly unknown[] | undefined	[]	Array of the items rendered by the virtual scroll.
maxHeight	string | number | undefined	—	Maximum component height
maxWidth	string | number | undefined	—	Maximum component width
minHeight	string | number | undefined	—	Minimum component height
minWidth	string | number | undefined	—	Minimum component width
renderless	boolean | undefined	—	Renderless mode: the component does not create its own scroll container and uses the nearest scrollable parent instead.
width	string | number | undefined	—	Component width

Slots

Name	Type	Description
default	CdsVirtualScrollSlot<any> & { itemRef?: TemplateRef | undefined; }	Content of a single list item. In renderless mode it additionally receives itemRef.

Exposed

Name	Type	Description
calculateVisibleItems	() => void	Recalculates the window of visible items — needed after their height changes outside the update cycle.
scrollToIndex	(index: number) => void	Scrolls the list to the item with the given index.

CdsVirtualScrollItem

Props

Name	Type	Default	Description
renderless	boolean | undefined	—	Renderless mode: the item renders only the slot content, without a wrapper.

Events

Name	Type	Description
update:height	[height: number]	Tells the virtual list that the height of the item has changed.

Slots

Name	Type	Description
default	{ itemRef: TemplateRef; }	Content of the item. In renderless mode it receives itemRef to measure the height.