Выпадающие списки CdsSelect и CdsAutocomplete, как и дерево CdsTree, уже виртуализируют свои элементы — оборачивать их не нужно. Короткий список — до пары сотен строк — рендерите обычным CdsList: виртуализация выигрыша не даст.

Вариации

Фиксированная высота

Проп height задаёт высоту области просмотра — внутри неё появляется прокрутка. Если все строки одной высоты, укажите item-height: компонент не будет измерять каждую строку, а позиции и полоса прокрутки будут точными с первого рендера.

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>

Динамическая высота

Без item-height компонент измеряет строки автоматически — подходит для контента переменной длины: комментариев, сообщений, описаний. Высоты уточняются по мере прокрутки, поэтому полоса прокрутки может слегка сдвигаться.

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 убирает собственный скролл-контейнер: компонент слушает прокрутку ближайшего скроллируемого родителя, а строки рендерит без обёрток. Слот дополнительно получает itemRef — привяжите его к корневому узлу строки, чтобы компонент знал её высоту. Так список встраивается в уже существующую прокрутку — панели или всей страницы. Скроллируемому родителю задайте position: relative — от него компонент отсчитывает позиции строк.

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>

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

Storybook

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

Поиск по каталогу

Передавайте в items уже отфильтрованный массив: computed пересчитывает записи по вводу, а компонент подхватывает новый список сам. item-key="id" привязывает строки к записям, а не к позициям в массиве — при фильтрации строки не перепутаются.

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>

Быстрый переход по журналу

Компонент отдаёт метод scrollToIndex — получите его через ref и прокручивайте список программно. Кнопки месяцев считают индекс первой операции месяца; с фиксированным item-height переход попадает точно в нужную строку.

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>

Выбор в длинном списке

Строки за пределами экрана не существуют в DOM, поэтому состояние выбора храните в данных, а не в самих строках. В демо отмеченные id лежат в Set: чекбокс строки читает его и меняет по клику — выбор переживает любую прокрутку.

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

Пропсы

Имя	Тип	По умолчанию	Описание
height	string | number | undefined	—	Высота компонента
itemHeight	string | number | undefined	null	Высота одного элемента в пикселях. Если не задана — высота измеряется автоматически.
itemKey	SelectItemKey	null	Ключ элемента для идентификации (имя поля, путь или функция). По умолчанию используется индекс.
items	readonly unknown[] | undefined	[]	Массив элементов, которые отрисовываются виртуальным скроллом.
maxHeight	string | number | undefined	—	Максимальная высота компонента
maxWidth	string | number | undefined	—	Максимальная ширина компонента
minHeight	string | number | undefined	—	Минимальная высота компонента
minWidth	string | number | undefined	—	Минимальная ширина компонента
renderless	boolean | undefined	—	Безрамочный режим: компонент не создаёт собственный скролл-контейнер, а использует ближайший скроллируемый родитель.
width	string | number | undefined	—	Ширина компонента

Слоты

Имя	Тип	Описание
default	CdsVirtualScrollSlot<any> & { itemRef?: TemplateRef | undefined; }	Содержимое одного элемента списка. В режиме renderless дополнительно получает itemRef.

Exposed

Имя	Тип	Описание
calculateVisibleItems	() => void	Пересчитывает окно видимых элементов — нужно после изменения их высоты вне цикла обновления.
scrollToIndex	(index: number) => void	Прокручивает список к элементу с указанным индексом.

CdsVirtualScrollItem

Пропсы

Имя	Тип	По умолчанию	Описание
renderless	boolean | undefined	—	Безрамочный режим: элемент рендерит только содержимое слота без обёртки.

События

Имя	Тип	Описание
update:height	[height: number]	Сообщает виртуальному списку об изменении высоты элемента.

Слоты

Имя	Тип	Описание
default	{ itemRef: TemplateRef; }	Содержимое элемента. В режиме renderless получает itemRef для измерения высоты.