For common tasks there are ready-made components built on the overlay: a dialog — CdsModal, a list of actions next to an activator — CdsMenu, a hint on hover — CdsTooltip, notifications — CdsToast. CdsOverlay is for when none of them fits.

Anatomy

An overlay consists of two parts: the scrim, which dims the page and intercepts clicks, and the content — the contents of the default slot. The content is moved to the end of body, so the overlay does not depend on the overflow and z-index of the parent blocks.

Storybook

Variations

Opening and closing

v-model controls the visibility. An open overlay closes on a click outside the content and on the Esc key.

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>

The persistent prop turns both ways off: the overlay closes only through v-model — for example, by a button inside the content. On a click outside, the content answers with a light "shake"; remove it with the no-click-animation prop if you do not need the 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

The activator slot saves you from a manual v-model: pass the slot props (v-bind="props") to an element — and a click on it will open the overlay. The open-on-hover and open-on-focus props switch the opening to hover or focus, and activator="parent" makes the parent element the activator.

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

The scrim is on by default: it dims the page and shows that the interface under the overlay is unavailable. The :scrim="false" prop removes it — a click outside still closes the overlay. The opacity prop tunes the dimming density, and a string in scrim sets a custom color for the 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>

Limiting to a container

The contained prop locks the overlay inside the parent block: the scrim and the content do not leave its bounds, and the rest of the page keeps working. The parent must have position: relative. To center the content inside the block rather than relative to the screen, pass the container to target and turn on 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>

Positioning

By default the content is centered relative to the screen — this is what the static strategy and the location prop are responsible for. The location-strategy="connected" strategy attaches the content to the activator: location sets the side, offset — the distance to it. If there is not enough room near the screen edge, the content flips to the opposite side — that is how CdsMenu works.

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>

Behavior on scroll

The scroll-strategy prop decides what happens to the page and the overlay on scroll: block (the default) blocks the page scroll, close closes the overlay, reposition recomputes the position of the content following the target, none does nothing.

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>

Animation

The transition prop changes the animation of showing and hiding the content.

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>

Slots

Slot	Description
activator	The element that opens the overlay. Bind the slot props (props) to it
default	The overlay content. Receives isActive — use it to close the overlay from inside

Guidelines

Storybook

Scenarios

Loading on top of a block

While the data of a block is being updated, a contained overlay with CdsProgressCircle covers only that block: the user sees that loading is in progress and keeps working with the rest of the page. persistent prevents closing the overlay by an accidental click, and scroll-strategy="none" does not block the page scroll.

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>

Image preview

A click on a thumbnail opens the image at full size on top of the dimmed page. A dense scrim (opacity="0.85") removes the visual noise, and the preview closes the usual way — by a click outside or the Esc key, no separate button needed.

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>

Onboarding hint

A hint about a new feature is a panel attached to an element by the connected strategy; in a real interface you open it programmatically, for example by a first-visit flag, here — by a click on a button. Without a scrim (:scrim="false") the hint does not get in the way of working with the page, persistent protects it from an accidental close — it disappears only by the "Понятно" button, and scroll-strategy="reposition" keeps it next to the activator on scroll.

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

Props

Name	Type	Default	Description
absolute	boolean | undefined	—	Positions the element absolutely instead of fixed. This is useful for overlays that must stay inside a certain area, for example inside a container with position: relative.
activator	(string & {}) | Element | "parent" | ComponentPublicInstance | undefined	—	The element that activates the component
activatorProps	Record<string, any> | undefined	{}	Props for the activator element
attach	string | boolean | Element | undefined	—	Sets the DOM element the overlay content is moved to. It accepts a direct element reference, a querySelector string, or true to disable moving. By default the body element is used. Changing this prop is usually not recommended except for edge cases: the default positioning algorithm handles most scenarios better than it can without moving, and unexpected behavior may appear if the menu ends up being a child of its activator.
captureFocus	boolean | undefined	—	Returns the focus back into the content if it has left it — for example on Tab from the end of the page. A mouse click does not steal the focus.
closeDelay	string | number | undefined	—	Delay in milliseconds before the component closes. Works only together with open-on-hover.
closeOnBack	boolean | undefined	true	Closes the overlay content when the browser Back button is pressed or $router.back() is called, cancelling the original navigation. persistent overlays cancel the navigation and animate as if they were clicked outside instead of closing.
closeOnContentClick	boolean | undefined	—	Hide the component on a click on the content
contained	boolean | undefined	—	Limits the size of the component and of its grid to the offset parent. Implies the absolute and attach props. (Note: the parent element must have position: relative.)
contentClass	any	—	Applies a custom class to the content element. This is handy because the content is moved to the beginning of the cds-app component (unless attach is set) and cannot be selected with classes passed to the component directly.
contentProps	any	—	Applies custom props to the moved content
disabled	boolean | null | undefined	null	Disabled state
eager	boolean | undefined	—	Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO.
height	string | number | undefined	—	Component height
location	Anchor | undefined	'bottom'	Sets the anchor point used to position the component, aligning it horizontally, vertically or in both directions
locationStrategy	"static" | "connected" | LocationStrategyFunction | undefined	'static'	Sets the way the overlay content is positioned. By default static is used, which centers the content in its container. Use connected to attach the content to the activator element.
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
modelValue	boolean | undefined	—	The v-model value of the component. If the component supports the multiple prop, an empty array is used by default.
noClickAnimation	boolean | undefined	—	Disables the bounce effect on a click outside the content element when persistent is set.
offset	string | number | number[] | undefined	—	Increases the distance to the target. If two numbers are passed, the second one shifts the anchor sideways, away from the target.
opacity	string | number | undefined	—	Opacity of the scrim element. Applies only when scrim=true.
openDelay	string | number | undefined	—	Delay in milliseconds before the component opens. Works only together with open-on-hover.
openOnClick	boolean | undefined	—	Show the component on a click on the activator
openOnFocus	boolean | undefined	—	Show the component when the activator gets focus
openOnHover	boolean | undefined	—	Show the component on hover over the activator
origin	Anchor | "auto" | "overlap" | undefined	'auto'	Sets the anchor point of the overlay content that is aligned with the location anchor of the target. With "auto" the opposite side of the location point is used. With "overlap" the same anchor point is used, so the overlay overlaps the target. It also sets the CSS transform-origin property for the enter/leave transitions.
persistent	boolean | undefined	—	A click outside the element or the Esc key does not close it.
retainFocus	boolean | undefined	—	Traps Tab navigation inside the content: from the last focusable element the focus moves to the first one and back.
scrim	string | boolean | undefined	true	Backdrop shown while the overlay is active. Accepts true/false to toggle the backdrop and a string to set its color.
scrollStrategy	"none" | "close" | "block" | "reposition" | ScrollStrategyFunction | undefined	'block'	Strategy applied when the component is active and the user scrolls the page.
stickToTarget	boolean | undefined	—	Lets the overlay content go off screen while scrolling.
target	(string & {}) | Element | "parent" | ComponentPublicInstance | "cursor" | [x: number, y: number] | undefined	—	When locationStrategy is set to "connected", specify the element or the array of x, y coordinates the overlay is positioned against. By default the activator element is used.
theme	string | undefined	—	Component theme
transition	string | boolean | (TransitionProps & { component?: Component | undefined; }) | null | undefined	'fade-transition'	Transition animation
viewportMargin	string | number | undefined	12	Sets a custom viewport margin for the overlay content
width	string | number | undefined	—	Component width
zIndex	string | number | undefined	2000	The z-index value of the component.

Events

Name	Type	Description
afterEnter	[]	Fires after the opening animation has finished.
afterLeave	[]	Fires after the closing animation has finished.
click:outside	[value: MouseEvent]	Fires on a click outside the overlay.
keydown	[value: KeyboardEvent]	Fires on a key press while the overlay is open.
update:modelValue	[value: boolean]	Fires when the overlay opens or closes. Passes the new visibility state.

Slots

Name	Type	Description
activator	{ isActive: boolean; props: Record<string, any>; targetRef: TemplateRef; }	Slot for the element that acts as the activator of the overlay.
default	{ isActive: Ref<boolean, boolean>; }	Slot for the overlay content.

Exposed

Name	Type	Description
activatorEl	HTMLElement | undefined	The DOM element of the activator.
activatorRef	TemplateRef	Template ref for assigning the activator manually.
animateClick	() => void	Runs the bounce animation of the content — the same as on a click outside a persistent overlay.
contentEl	HTMLElement | undefined	The DOM element of the overlay content.
globalTop	boolean	Whether the overlay is the top one in the global stack of open overlays.
rootEl	HTMLElement | undefined	The root DOM element of the overlay.
scrimEl	HTMLElement | undefined	The DOM element of the scrim that dims the page.
targetEl	HTMLElement | undefined	The DOM element of the positioning target.
targetRef	TemplateRef	Template ref for assigning the positioning target manually.
updateLocation	((e: Event) => void) | undefined	Recalculates the position of the content relative to the target.