Для типовых задач есть готовые компоненты на базе оверлея: диалог — CdsModal, список действий у активатора — CdsMenu, подсказка при наведении — CdsTooltip, уведомления — CdsToast. CdsOverlay нужен, когда ни один из них не подходит.

Анатомия

Оверлей состоит из двух частей: подложки, которая затемняет страницу и перехватывает клики, и контента — содержимого слота default. Контент переносится в конец body, поэтому оверлей не зависит от overflow и z-index родительских блоков.

Storybook

Вариации

Открытие и закрытие

Показом управляет v-model. Открытый оверлей закрывается кликом мимо контента и клавишей Esc.

Sandbox Storybook

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

const overlay = ref(false);
</script>

<template>
  <div class="flex justify-center">
    <CdsButton text="Показать оверлей" @click="overlay = true" />

    <CdsOverlay v-model="overlay" location="center center">
      <div class="w-[320px] rounded-200 bg-surface-primary p-4">
        <p>Оверлей открыт. Кликните мимо контента или нажмите <code>Esc</code>, чтобы закрыть его.</p>
      </div>
    </CdsOverlay>
  </div>
</template>

Проп persistent отключает оба способа: оверлей закроется только через v-model — например, кнопкой внутри контента. На клик мимо контент отвечает лёгким «покачиванием»; уберите его пропом no-click-animation, если анимация не нужна.

Sandbox Storybook

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

const overlay = ref(false);
</script>

<template>
  <div class="flex justify-center">
    <CdsButton text="Открыть persistent-оверлей" @click="overlay = true" />

    <CdsOverlay v-model="overlay" persistent location="center center">
      <div class="flex w-[320px] flex-col gap-2 rounded-200 bg-surface-primary p-4">
        <p>Клик мимо и <code>Esc</code> не закрывают оверлей — контент отвечает лёгким «покачиванием».</p>
        <CdsButton class="self-end" variant="soft" color="brand" text="Закрыть" @click="overlay = false" />
      </div>
    </CdsOverlay>
  </div>
</template>

Активатор

Слот activator избавляет от ручного v-model: передайте пропсы слота (v-bind="props") элементу — и клик по нему будет открывать оверлей. Пропсы open-on-hover и open-on-focus переключают открытие на наведение или фокус, а activator="parent" делает активатором родительский элемент.

Sandbox Storybook

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

<template>
  <div class="flex justify-center">
    <CdsOverlay location="center center">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand" text="Открыть через активатор" />
      </template>

      <div class="w-[320px] rounded-200 bg-surface-primary p-4">
        <p>Оверлей открылся кликом по активатору — <code>v-model</code> и свой обработчик не понадобились.</p>
      </div>
    </CdsOverlay>
  </div>
</template>

Подложка

Подложка включена по умолчанию: она затемняет страницу и показывает, что интерфейс под оверлеем недоступен. Проп :scrim="false" убирает её — клик мимо по-прежнему закрывает оверлей. Плотность затемнения настраивает opacity, а строка в scrim задаёт свой цвет подложки.

Sandbox Storybook

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

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsOverlay location="center center">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand" text="Обычная подложка" />
      </template>
      <div class="w-[280px] rounded-200 bg-surface-primary p-4">Подложка по умолчанию.</div>
    </CdsOverlay>

    <CdsOverlay :scrim="false" location="center center">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand" text="Без подложки" />
      </template>
      <div class="w-[280px] rounded-200 border bg-surface-primary p-4">
        Страница под оверлеем не затемнена, клик мимо всё равно закрывает контент.
      </div>
    </CdsOverlay>

    <CdsOverlay opacity="0.9" location="center center">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand" text="Плотная подложка" />
      </template>
      <div class="w-[280px] rounded-200 bg-surface-primary p-4">
        <code>opacity="0.9"</code> почти полностью скрывает страницу.
      </div>
    </CdsOverlay>
  </div>
</template>

Ограничение контейнером

Проп contained запирает оверлей внутри родительского блока: подложка и контент не выходят за его границы, а остальная страница продолжает работать. Родитель должен иметь position: relative. Чтобы контент центрировался в блоке, а не относительно экрана, передайте контейнер в target и включите location-strategy="connected".

Sandbox Storybook

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

const container = ref<HTMLElement>();
const overlay = ref(false);
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col gap-2">
    <div ref="container" class="relative h-[180px] overflow-hidden rounded-200 bg-surface-secondary p-4">
      <p>Оверлей появится поверх этого блока, а остальная страница продолжит работать.</p>

      <CdsOverlay
        v-model="overlay"
        contained
        location-strategy="connected"
        :target="container"
        location="center center"
        scroll-strategy="none"
      >
        <div class="rounded-200 bg-surface-primary p-4">Контент внутри блока</div>
      </CdsOverlay>
    </div>

    <CdsButton class="self-center" variant="soft" color="brand" text="Показать оверлей" @click="overlay = !overlay" />
  </div>
</template>

Позиционирование

По умолчанию контент центрируется относительно экрана — за это отвечает стратегия static и проп location. Стратегия location-strategy="connected" привязывает контент к активатору: location задаёт сторону, offset — расстояние до неё. Если места у края экрана не хватает, контент перевернётся на противоположную сторону — так работает CdsMenu.

Sandbox Storybook

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

const locations = ['top', 'bottom', 'end'] as const;
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsOverlay
      v-for="location in locations"
      :key="location"
      location-strategy="connected"
      :location="location"
      :offset="8"
      :scrim="false"
      scroll-strategy="reposition"
    >
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand" :text="`location=&quot;${location}&quot;`" />
      </template>

      <div class="rounded-200 border bg-surface-primary px-4 py-2">Панель у активатора</div>
    </CdsOverlay>
  </div>
</template>

Поведение при прокрутке

Проп scroll-strategy определяет, что происходит со страницей и оверлеем при прокрутке: block (по умолчанию) блокирует прокрутку страницы, close закрывает оверлей, reposition пересчитывает позицию контента вслед за целью, none не делает ничего.

Sandbox Storybook

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

const strategies = ['block', 'close', 'reposition', 'none'] as const;
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsOverlay
      v-for="strategy in strategies"
      :key="strategy"
      location-strategy="connected"
      location="bottom"
      :offset="8"
      :scrim="false"
      :scroll-strategy="strategy"
    >
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand" :text="strategy" />
      </template>

      <div class="w-[260px] rounded-200 border bg-surface-primary px-4 py-2">
        Панель открыта — покрутите страницу и посмотрите, что произойдёт.
      </div>
    </CdsOverlay>
  </div>
</template>

Анимация

Проп transition меняет анимацию появления и скрытия контента.

Sandbox Storybook

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

const transitions = ['fade-transition', 'scale-transition', 'slide-transition-y'] as const;
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsOverlay v-for="transition in transitions" :key="transition" :transition="transition" location="center center">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="neutral" :text="transition" />
      </template>

      <div class="w-[280px] rounded-200 bg-surface-primary p-4">
        <code>{{ transition }}</code>
      </div>
    </CdsOverlay>
  </div>
</template>

Слоты

Слот	Описание
activator	Элемент, открывающий оверлей. Пропсы слота (props) вешают на него обработчики
default	Контент оверлея. Получает isActive — им можно закрыть оверлей изнутри

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

Storybook

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

Загрузка поверх блока

Пока данные блока обновляются, contained-оверлей с CdsProgressCircle накрывает только этот блок: пользователь видит, что идёт загрузка, и продолжает работать с остальной страницей. persistent не даёт закрыть оверлей случайным кликом, а scroll-strategy="none" не блокирует прокрутку страницы.

Sandbox Storybook

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

const snapshots = [
  [
    { label: 'Выручка', value: '1 240 500 ₽' },
    { label: 'Заказы', value: '318' },
    { label: 'Конверсия', value: '4,2%' }
  ],
  [
    { label: 'Выручка', value: '1 262 300 ₽' },
    { label: 'Заказы', value: '327' },
    { label: 'Конверсия', value: '4,4%' }
  ]
];

const card = ref<HTMLElement>();
const loading = ref(false);
const index = ref(0);

const refresh = () => {
  loading.value = true;

  setTimeout(() => {
    index.value = (index.value + 1) % snapshots.length;
    loading.value = false;
  }, 1600);
};
</script>

<template>
  <div ref="card" class="relative m-auto w-[360px] overflow-hidden rounded-200 bg-surface-secondary p-4">
    <div class="flex items-center justify-between">
      <span class="h4">Продажи за сегодня</span>
      <CdsButton variant="soft" color="neutral" size="sm" icon="refresh" aria-label="Обновить" @click="refresh" />
    </div>

    <div class="mt-2 flex flex-col gap-1">
      <div v-for="row in snapshots[index]" :key="row.label" class="flex justify-between">
        <span class="text-content-secondary">{{ row.label }}</span>
        <span>{{ row.value }}</span>
      </div>
    </div>

    <CdsOverlay
      v-model="loading"
      contained
      persistent
      no-click-animation
      location-strategy="connected"
      :target="card"
      location="center center"
      scroll-strategy="none"
    >
      <CdsProgressCircle indeterminate :size="40" />
    </CdsOverlay>
  </div>
</template>

Просмотр изображения

Клик по миниатюре открывает изображение в полный размер поверх затемнённой страницы. Плотная подложка (opacity="0.85") убирает визуальный шум, а закрывается просмотр стандартно — кликом мимо или клавишей Esc, отдельная кнопка не нужна.

Sandbox Storybook

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

const preview = ref(false);
</script>

<template>
  <div class="flex justify-center">
    <button type="button" class="w-[220px] cursor-pointer" aria-label="Открыть изображение" @click="preview = true">
      <CdsImage src="/images/temp/city.webp" class="rounded-200" cover :aspect-ratio="16 / 10" alt="Вид на город" />
    </button>

    <CdsOverlay v-model="preview" location="center center" opacity="0.85">
      <figure class="flex flex-col items-center gap-2">
        <CdsImage
          src="/images/temp/city.webp"
          class="max-h-[70vh] w-[min(800px,90vw)] rounded-200"
          alt="Вид на город"
        />
        <figcaption class="text-100 text-content-on-dark">
          Кликните мимо изображения или нажмите Esc, чтобы закрыть
        </figcaption>
      </figure>
    </CdsOverlay>
  </div>
</template>

Онбординг-подсказка

Подсказка о новой возможности — панель, привязанная к элементу стратегией connected; в реальном интерфейсе её открывают программно, например по флагу первого визита, здесь — кликом по кнопке. Без подложки (:scrim="false") подсказка не мешает работать со страницей, persistent защищает от случайного закрытия — она исчезает только по кнопке «Понятно», а scroll-strategy="reposition" держит её у активатора при прокрутке.

Sandbox Storybook

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

const hint = ref(false);
</script>

<template>
  <div class="flex justify-center">
    <CdsOverlay
      v-model="hint"
      location-strategy="connected"
      location="bottom"
      :offset="8"
      :scrim="false"
      persistent
      no-click-animation
      :close-on-back="false"
      scroll-strategy="reposition"
    >
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand" prepend-icon="adjust" text="Фильтры" />
      </template>

      <div class="flex w-[260px] flex-col gap-2 rounded-200 border bg-surface-primary p-4">
        <p class="text-100">
          Теперь фильтры можно сохранять: настройте условия один раз и возвращайтесь к ним в один клик.
        </p>
        <CdsButton class="self-end" size="sm" variant="soft" color="brand" text="Понятно" @click="hint = false" />
      </div>
    </CdsOverlay>
  </div>
</template>

API

Пропсы

Имя	Тип	По умолчанию	Описание
absolute	boolean | undefined	—	Указывает, что элемент должен быть позиционирован абсолютно, а не фиксированно. Это может быть полезно для оверлеев, которые должны быть ограничены определенной областью, например, внутри контейнера с position: relative.
activator	(string & {}) | Element | "parent" | ComponentPublicInstance | undefined	—	Элемент, который будет активировать компонент
activatorProps	Record<string, any> | undefined	{}	Свойства для элемента активатора
attach	string | boolean | Element | undefined	—	Указывает, в какой элемент DOM следует переместить содержимое overlay. Может быть прямой ссылкой на элемент, строкой querySelector или значением true для отключения перемещения. По умолчанию используется элемент body. Как правило, не рекомендуется изменять это свойство, за исключением крайних случаев: алгоритм позиционирования по умолчанию должен справляться с большинством сценариев лучше, чем это возможно без перемещения, и может возникнуть непредвиденное поведение, если меню окажется дочерним элементом своего активатора.
captureFocus	boolean | undefined	—	Возвращает фокус внутрь контента, если он ушёл за его пределы — например, по Tab с конца страницы. Клик мышью фокус не перехватывает.
closeDelay	string | number | undefined	—	Время ожидания в миллисекундах перед закрытием компонента. Работает только с параметром open-on-hover.
closeOnBack	boolean | undefined	true	Закрывает содержимое оверлея при нажатии кнопки «Назад» в браузере или вызове $router.back(), отменяя исходную навигацию. persistent оверлеи отменяют навигацию и анимируются так, как будто по ним щелкнули за пределами оверлея, вместо того чтобы закрываться.
closeOnContentClick	boolean | undefined	—	Скрыть компонент по клику на контент
contained	boolean | undefined	—	Ограничивает размер компонента и сетки в соответствии с его смещенным родительским элементом. Подразумевает использование свойств absolute и attach. (Примечание: родительский элемент должен иметь свойство position: relative.)
contentClass	any	—	Применяет пользовательский класс к отдельному элементу. Это удобно, поскольку содержимое перемещается в начало компонента cds-app (если не указан параметр attach) и не может быть выделено с помощью классов, переданных непосредственно в компонент.
contentProps	any	—	Применяет кастомные свойства (props) к перемещаемому контенту
disabled	boolean | null | undefined	null	Заблокированное состояние
eager	boolean | undefined	—	Принудительно рендерит содержимое компонента при его использовании. Это полезно, если у вас есть контент, который не отображается в DOM, но который необходимо проиндексировать для SEO.
height	string | number | undefined	—	Высота компонента
location	Anchor | undefined	'bottom'	Указывает точку привязки для позиционирования компонента с использованием ориентиров для выравнивания по горизонтали, по вертикали или по обоим направлениям
locationStrategy	"static" | "connected" | LocationStrategyFunction | undefined	'static'	Определяет способ позиционирования содержимого оверлея. По умолчанию используется значение static, при котором содержимое центрируется в контейнере. Используйте connected для привязки к элементу-активатору.
maxHeight	string | number | undefined	—	Максимальная высота компонента
maxWidth	string | number | undefined	—	Максимальная ширина компонента
minHeight	string | number | undefined	—	Минимальная высота компонента
minWidth	string | number | undefined	—	Минимальная ширина компонента
modelValue	boolean | undefined	—	Значение компонента v-model. Если компонент поддерживает свойство multiple, по умолчанию используется пустой массив.
noClickAnimation	boolean | undefined	—	Отключает эффект bounce при нажатии за пределами элемента контента при использовании атрибута persistent.
offset	string | number | number[] | undefined	—	Увеличивает расстояние до цели. Если передать два числа, второе значение смещает анкер вбок и в сторону от цели.
opacity	string | number | undefined	—	Прозрачность элемента «scrim». Применяется только в том случае, если св-во scrim=true.
openDelay	string | number | undefined	—	Время ожидания в миллисекундах перед открытием компонента. Работает только с параметром open-on-hover.
openOnClick	boolean | undefined	—	Показать компонент по клику на активатор
openOnFocus	boolean | undefined	—	Показать компонент по фокусу на активатор
openOnHover	boolean | undefined	—	Показать компонент по наведению на активатор
origin	Anchor | "auto" | "overlap" | undefined	'auto'	Устанавливает точку привязки для содержимого наложения, которая выравнивается по точке привязки «location» на объекте-цели. При значении «auto» используется противоположная сторона точки «location». При значении «overlap» используется та же точка привязки, в результате чего наложение перекрывает объект-цель. Также задает значение CSS-свойства transform-origin для transitions enter/leave.
persistent	boolean | undefined	—	Клик за пределами элемента или нажатие клавиши Esc не приведет к его закрытию.
retainFocus	boolean | undefined	—	Замыкает Tab-навигацию внутри контента: с последнего фокусируемого элемента фокус переходит на первый и наоборот.
scrim	string | boolean | undefined	true	Фон при активации overlay. Принимает значения true/false для включения фона и строку для определения цвета.
scrollStrategy	"none" | "close" | "block" | "reposition" | ScrollStrategyFunction | undefined	'block'	Стратегия, применяемая при активации компонента и прокрутке страницы пользователем.
stickToTarget	boolean | undefined	—	Позволяет контенту наложения выходить за пределы экрана при прокрутке.
target	(string & {}) | Element | "parent" | ComponentPublicInstance | "cursor" | [x: number, y: number] | undefined	—	Если для параметра locationStrategy задано значение «connected», необходимо указать элемент или массив координат x, y, относительно которых должен располагаться оверлей. По умолчанию в качестве такого элемента используется элемент-активатор.
theme	string | undefined	—	Тема компонента
transition	string | boolean | (TransitionProps & { component?: Component | undefined; }) | null | undefined	'fade-transition'	Анимация перехода
viewportMargin	string | number | undefined	12	Устанавливает пользовательские viewport margin для содержимого наложения
width	string | number | undefined	—	Ширина компонента
zIndex	string | number | undefined	2000	Значение z-index для компонента.

События

Имя	Тип	Описание
afterEnter	[]	Сработало после завершения анимации открытия.
afterLeave	[]	Сработало после завершения анимации закрытия.
click:outside	[value: MouseEvent]	Событие, которое срабатывает при клике вне оверлея.
keydown	[value: KeyboardEvent]	Сработало при нажатии клавиши, пока оверлей открыт.
update:modelValue	[value: boolean]	Сработало при открытии или закрытии оверлея. Передаёт новое состояние видимости.

Слоты

Имя	Тип	Описание
activator	{ isActive: boolean; props: Record<string, any>; targetRef: TemplateRef; }	Слот для элемента, который будет выступать в роли активатора для оверлея.
default	{ isActive: Ref<boolean, boolean>; }	Слот для контента оверлея.

Exposed

Имя	Тип	Описание
activatorEl	HTMLElement | undefined	DOM-элемент активатора.
activatorRef	TemplateRef	Template ref для назначения активатора вручную.
animateClick	() => void	Запускает bounce-анимацию контента — как при клике мимо persistent-оверлея.
contentEl	HTMLElement | undefined	DOM-элемент контента оверлея.
globalTop	boolean	Является ли оверлей верхним в глобальном стеке открытых оверлеев.
rootEl	HTMLElement | undefined	Корневой DOM-элемент оверлея.
scrimEl	HTMLElement | undefined	DOM-элемент подложки (scrim), затемняющей страницу.
targetEl	HTMLElement | undefined	DOM-элемент цели позиционирования.
targetRef	TemplateRef	Template ref для назначения цели позиционирования вручную.
updateLocation	((e: Event) => void) | undefined	Пересчитывает позицию контента относительно цели.