Для списка действий у элемента возьмите CdsMenu, для короткой подсказки — CdsTooltip, для уведомления о результате — CdsToast. Сложное содержимое окна — шапку, прокручиваемый текст и ряд кнопок — собирают из CdsCard.

Внутри окна работает CdsOverlay: он выводит контент поверх страницы, затемняет её, блокирует прокрутку и удерживает фокус внутри окна — по Tab не выбраться наружу, а после закрытия фокус возвращается на активатор. Поэтому пропсы открытия и позиционирования у модального окна общие с оверлеем.

Вариации

Активаторы

Окно открывает элемент-активатор — задать его можно тремя способами:

1. Через слот activator — пропсы из слота (v-bind="props") вешают на элемент обработчики и aria-атрибуты. Способ по умолчанию.
2. Через родителя — activator="parent" берёт элемент, внутри которого лежит CdsModal.
3. Через селектор — activator="#id" связывает окно с любым элементом страницы, даже далёким по разметке.

Sandbox Storybook

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

const slotModal = ref(false);
const parentModal = ref(false);
const siblingModal = ref(false);
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsModal v-model="slotModal">
      <template #activator="{ props }">
        <CdsButton v-bind="props">Активатор в слоте</CdsButton>
      </template>

      <span class="h4">Заголовок</span>
      <p>Модальное окно открыто активатором из слота</p>

      <div class="mt-4 flex justify-end">
        <CdsButton @click="slotModal = false">Закрыть</CdsButton>
      </div>
    </CdsModal>

    <CdsButton>
      Родительский элемент

      <CdsModal v-model="parentModal" activator="parent">
        <span class="h4">Заголовок</span>
        <p>Модальное окно открыто родительским элементом</p>

        <div class="mt-4 flex justify-end">
          <CdsButton @click="parentModal = false">Закрыть</CdsButton>
        </div>
      </CdsModal>
    </CdsButton>

    <CdsButton id="modal-activator">Соседний элемент</CdsButton>
    <CdsModal v-model="siblingModal" activator="#modal-activator">
      <span class="h4">Заголовок</span>
      <p>Модальное окно открыто соседним элементом по CSS-селектору</p>

      <div class="mt-4 flex justify-end">
        <CdsButton @click="siblingModal = false">Закрыть</CdsButton>
      </div>
    </CdsModal>
  </div>
</template>

Использование v-model

Состоянием окна можно управлять напрямую через v-model — без активатора. Так открывают окно из кода: по ответу сервера, из обработчика в таблице, из стора.

Sandbox Storybook

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

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

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsButton @click="modal = true">Открыть модальное окно</CdsButton>

    <CdsModal v-model="modal">
      <div class="flex items-center justify-between">
        <span class="h4">Заголовок</span>
        <CdsFunctionalButton icon="remove" aria-label="Закрыть" @click="modal = false" />
      </div>

      <p>Модальное окно без активатора: состоянием управляет v-model</p>
    </CdsModal>

    <div class="text-content-primary"><strong>v-model:</strong> {{ modal }}</div>
  </div>
</template>

Размеры

Проп size задаёт ширину окна: xs (250), sm (350), md (500, по умолчанию), lg (700), xl — почти на всю ширину экрана. Число вместо алиаса — точная ширина в пикселях. Высота всегда подстраивается под контент, а width и max-width переопределяют размер, когда нужна нестандартная сетка.

Sandbox Storybook

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

const sizes: Size[] = ['xs', 'sm', 'md', 'lg', 'xl'];

const size = ref<Size>('md');
const modal = ref(false);

const open = (value: Size) => {
  size.value = value;
  modal.value = true;
};
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsButton v-for="item in sizes" :key="item" variant="soft" color="brand" @click="open(item)">
      {{ item }}
    </CdsButton>

    <CdsModal v-model="modal" :size="size">
      <span class="h4">Размер {{ size }}</span>
      <p>Ширина окна задана пропом <code>size</code></p>

      <div class="mt-4 flex justify-end">
        <CdsButton @click="modal = false">Закрыть</CdsButton>
      </div>
    </CdsModal>
  </div>
</template>

Постоянные окна

Проп persistent отключает закрытие кликом мимо окна и клавишей Esc — закрыть окно можно только кнопками внутри. Клик мимо встряхивает окно, подсказывая, что ответить всё-таки придётся; анимацию убирает no-click-animation. Берите persistent, когда закрытие потеряет данные или пользователь обязан сделать выбор.

Sandbox Storybook

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

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

<template>
  <div class="flex justify-center">
    <CdsModal v-model="modal" persistent size="sm">
      <template #activator="{ props }">
        <CdsButton v-bind="props">Открыть модальное окно</CdsButton>
      </template>

      <span class="h4">Подтвердите действие</span>
      <p>Клик мимо окна и клавиша <code>Esc</code> его не закроют — ответьте одной из кнопок.</p>

      <div class="mt-4 flex justify-end gap-3">
        <CdsButton variant="soft" color="neutral" @click="modal = false">Отменить</CdsButton>
        <CdsButton @click="modal = false">Подтвердить</CdsButton>
      </div>
    </CdsModal>
  </div>
</template>

Скролл внутри окна

По умолчанию длинный контент прокручивается вместе с окном целиком. Проп scrollable фиксирует шапку и кнопки, а прокручивает только середину — для этого содержимое собирают из CdsCard: карточка становится поверхностью окна, зона прокрутки — её CdsCardText.

Sandbox Storybook

<script setup lang="ts">
import {
  CdsButton,
  CdsCard,
  CdsCardActions,
  CdsCardText,
  CdsDivider,
  CdsModal,
  CdsRadio,
  CdsRadioGroup
} from '@central-design-system/components';
import { ref } from 'vue';

const modal = ref(false);
const country = ref(null);

const countries = [
  'Австрия',
  'Бельгия',
  'Болгария',
  'Венгрия',
  'Германия',
  'Греция',
  'Дания',
  'Ирландия',
  'Испания',
  'Италия',
  'Латвия',
  'Литва',
  'Нидерланды',
  'Норвегия',
  'Польша',
  'Португалия',
  'Румыния',
  'Сербия',
  'Словакия',
  'Финляндия',
  'Франция',
  'Хорватия',
  'Чехия',
  'Швейцария',
  'Швеция',
  'Эстония'
];
</script>

<template>
  <div class="flex justify-center">
    <CdsModal v-model="modal" scrollable size="sm">
      <template #activator="{ props }">
        <CdsButton v-bind="props">Выбрать страну</CdsButton>
      </template>

      <template #default="{ isActive }">
        <CdsCard prepend-icon="search" title="Выберите страну">
          <CdsDivider />

          <CdsCardText class="h-[300px]">
            <CdsRadioGroup v-model="country">
              <CdsRadio v-for="item of countries" :key="item" :label="item" :value="item" />
            </CdsRadioGroup>
          </CdsCardText>

          <CdsDivider />

          <CdsCardActions class="justify-end gap-2">
            <CdsButton text="Сохранить" @click="isActive.value = false" />
          </CdsCardActions>
        </CdsCard>
      </template>
    </CdsModal>
  </div>
</template>

На весь экран

Проп fullscreen разворачивает окно на весь экран: пропсы размеров игнорируются, отступы и скругления убираются. Подходит для просмотра документов и сложных форм на небольших экранах.

Sandbox Storybook

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

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

<template>
  <div class="flex justify-center">
    <CdsModal v-model="modal" fullscreen>
      <template #activator="{ props }">
        <CdsButton v-bind="props">Открыть на весь экран</CdsButton>
      </template>

      <div class="flex items-center justify-between">
        <span class="h4">Окно на весь экран</span>
        <CdsFunctionalButton icon="remove" aria-label="Закрыть" @click="modal = false" />
      </div>

      <p class="mt-2">
        Проп <code>fullscreen</code> разворачивает окно на весь экран: пропсы размеров игнорируются, скругления и
        отступы от краёв убираются. Такой режим подходит для просмотра документов и сложных форм на небольших экранах.
      </p>

      <div class="mt-auto flex justify-end">
        <CdsButton @click="modal = false">Закрыть</CdsButton>
      </div>
    </CdsModal>
  </div>
</template>

Анимации

По умолчанию окно вырастает из активатора и сжимается обратно — так видно, откуда оно появилось. Проп transition меняет анимацию: готовые modal-transition-top и modal-transition-bottom выдвигают окно от края экрана, подойдёт и любая своя CSS-анимация.

Sandbox Storybook

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

const modalTop = ref(false);
const modalBottom = ref(false);
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsModal v-model="modalTop" transition="modal-transition-top" size="sm">
      <template #activator="{ props }">
        <CdsButton v-bind="props">Сверху</CdsButton>
      </template>

      <span class="h4">Заголовок</span>
      <p>Окно выезжает сверху</p>

      <div class="mt-4 flex justify-end">
        <CdsButton @click="modalTop = false">Закрыть</CdsButton>
      </div>
    </CdsModal>

    <CdsModal v-model="modalBottom" transition="modal-transition-bottom" size="sm">
      <template #activator="{ props }">
        <CdsButton v-bind="props">Снизу</CdsButton>
      </template>

      <span class="h4">Заголовок</span>
      <p>Окно выезжает снизу</p>

      <div class="mt-4 flex justify-end">
        <CdsButton @click="modalBottom = false">Закрыть</CdsButton>
      </div>
    </CdsModal>
  </div>
</template>

Слоты

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

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

Storybook

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

Подтверждение удаления

Необратимое действие подтверждают компактным окном size="sm": заголовок называет действие, текст уточняет, что именно будет удалено, главная кнопка повторяет глагол из заголовка. Одно окно обслуживает весь список — перед открытием в него кладут выбранную запись.

Sandbox Storybook

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

const initial = ['Договор поставки № 42', 'Смета на монтаж', 'Акт сверки за июнь'];

const drafts = ref([...initial]);
const modal = ref(false);
const pending = ref('');

const askDelete = (draft: string) => {
  pending.value = draft;
  modal.value = true;
};

const confirmDelete = () => {
  drafts.value = drafts.value.filter((draft) => draft !== pending.value);
  modal.value = false;
};
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col items-center gap-2">
    <CdsList v-if="drafts.length" class="w-full">
      <CdsListItem v-for="draft in drafts" :key="draft" :title="draft">
        <template #append>
          <CdsFunctionalButton icon="delete" :aria-label="`Удалить: ${draft}`" @click="askDelete(draft)" />
        </template>
      </CdsListItem>
    </CdsList>

    <CdsButton v-else variant="soft" color="brand" @click="drafts = [...initial]">Восстановить список</CdsButton>

    <CdsModal v-model="modal" size="sm">
      <span class="h4">Удалить черновик?</span>
      <p class="mt-2">«{{ pending }}» будет удалён без возможности восстановления.</p>

      <div class="mt-4 flex justify-end gap-3">
        <CdsButton variant="soft" color="neutral" @click="modal = false">Отмена</CdsButton>
        <CdsButton @click="confirmDelete">Удалить</CdsButton>
      </div>
    </CdsModal>
  </div>
</template>

Форма в модальном окне

Короткую форму открывают поверх списка, чтобы не уводить пользователя на отдельную страницу. persistent защищает введённое от случайного клика мимо, кнопка отправки показывает loading, а «Отмена» блокируется на время запроса. Поля сбрасываются в событии after-leave — после анимации закрытия, чтобы значения не мигали в ещё видимом окне.

Sandbox Storybook

<script setup lang="ts">
import {
  CdsButton,
  CdsCard,
  CdsCardActions,
  CdsCardText,
  CdsDivider,
  CdsForm,
  CdsModal,
  CdsTextInput
} from '@central-design-system/components';
import { ref } from 'vue';

const modal = ref(false);
const loading = ref(false);
const name = ref('');
const email = ref('');

const submit = async () => {
  loading.value = true;

  // Имитация запроса к серверу
  await new Promise((resolve) => setTimeout(resolve, 1500));

  loading.value = false;
  modal.value = false;
};

const reset = () => {
  name.value = '';
  email.value = '';
};
</script>

<template>
  <div class="flex justify-center">
    <CdsModal v-model="modal" persistent size="sm" @after-leave="reset">
      <template #activator="{ props }">
        <CdsButton v-bind="props">Пригласить сотрудника</CdsButton>
      </template>

      <CdsForm @submit.prevent="submit">
        <CdsCard title="Пригласить сотрудника">
          <CdsDivider />

          <CdsCardText class="flex flex-col gap-2">
            <CdsTextInput v-model="name" label="Имя" />
            <CdsTextInput v-model="email" label="Рабочая почта" placeholder="name@company.ru" />
          </CdsCardText>

          <CdsDivider />

          <CdsCardActions class="justify-end gap-2">
            <CdsButton variant="soft" color="neutral" :disabled="loading" @click="modal = false">Отмена</CdsButton>
            <CdsButton type="submit" :loading="loading">Отправить приглашение</CdsButton>
          </CdsCardActions>
        </CdsCard>
      </CdsForm>
    </CdsModal>
  </div>
</template>

Соглашение с прокруткой

Документ, требующий явного ответа, показывают в окне с persistent и scrollable: текст прокручивается, а кнопки «Принять» и «Отклонить» всегда на виду. Закрыть окно, не ответив, не получится — решение фиксируется только кнопками.

Sandbox Storybook

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

const modal = ref(false);
const accepted = ref<boolean | null>(null);

const answer = (value: boolean) => {
  accepted.value = value;
  modal.value = false;
};
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsButton @click="modal = true">Открыть условия</CdsButton>

    <div v-if="accepted !== null" class="text-content-primary">
      {{ accepted ? 'Условия приняты' : 'Условия отклонены' }}
    </div>

    <CdsModal v-model="modal" persistent scrollable size="sm">
      <CdsCard title="Условия использования">
        <CdsDivider />

        <CdsCardText class="h-[300px]">
          <p v-for="n in 6" :key="n" class="mb-2">
            {{ n }}. Стороны признают юридическую силу документов, подписанных в системе, и обязуются соблюдать
            конфиденциальность учётных данных. Оператор вправе обновлять условия, уведомив пользователей заранее.
          </p>
        </CdsCardText>

        <CdsDivider />

        <CdsCardActions class="justify-end gap-2">
          <CdsButton variant="soft" color="neutral" @click="answer(false)">Отклонить</CdsButton>
          <CdsButton @click="answer(true)">Принять</CdsButton>
        </CdsCardActions>
      </CdsCard>
    </CdsModal>
  </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	true	Возвращает фокус внутрь контента, если он ушёл за его пределы — например, по 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.
fullscreen	boolean | undefined	—	Разворачивает модальное окно на весь экран.
height	string | number | undefined	—	Высота компонента
location	Anchor | undefined	'center center'	Указывает точку привязки для позиционирования компонента с использованием ориентиров для выравнивания по горизонтали, по вертикали или по обоим направлениям
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	'center center'	Устанавливает точку привязки для содержимого наложения, которая выравнивается по точке привязки «location» на объекте-цели. При значении «auto» используется противоположная сторона точки «location». При значении «overlap» используется та же точка привязки, в результате чего наложение перекрывает объект-цель. Также задает значение CSS-свойства transform-origin для transitions enter/leave.
persistent	boolean | undefined	—	Клик за пределами элемента или нажатие клавиши Esc не приведет к его закрытию.
retainFocus	boolean | undefined	true	Замыкает Tab-навигацию внутри контента: с последнего фокусируемого элемента фокус переходит на первый и наоборот.
scrim	string | boolean | undefined	true	Фон при активации overlay. Принимает значения true/false для включения фона и строку для определения цвета.
scrollable	boolean | undefined	—	Включает прокрутку контента внутри модального окна.
scrollStrategy	"none" | "close" | "block" | "reposition" | ScrollStrategyFunction | undefined	'block'	Стратегия, применяемая при активации компонента и прокрутке страницы пользователем.
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Размер компонента
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; }) | { component: Component; } | null | undefined	{ component: CdsModalTransition }	Анимация перехода
viewportMargin	string | number | undefined	12	Устанавливает пользовательские viewport margin для содержимого наложения
width	string | number | undefined	—	Ширина компонента
zIndex	string | number | undefined	2400	Значение z-index для компонента.

События

Имя	Тип	Описание
afterEnter	[]	Событие завершения анимации открытия модального окна.
afterLeave	[]	Событие завершения анимации закрытия модального окна.
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	Пересчитывает позицию контента относительно цели.