For a list of actions on an element take CdsMenu, for a short hint — CdsTooltip, for a notification about the result — CdsToast. Complex modal content — a header, scrollable text and a row of buttons — is assembled from CdsCard.

Inside the modal works CdsOverlay: it renders the content on top of the page, dims it, blocks scrolling and keeps the focus inside the modal — Tab will not get you out, and after closing the focus returns to the activator. That is why the opening and positioning props of the modal are shared with the overlay.

Variations

Activators

The modal is opened by an activator element — you can set it in three ways:

1. Through the activator slot — the props from the slot (v-bind="props") attach the handlers and the aria attributes to the element. The default way.
2. Through the parent — activator="parent" takes the element that CdsModal is placed inside of.
3. Through a selector — activator="#id" links the modal to any element on the page, even a distant one in the markup.

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>

Using v-model

The state of the modal can be controlled directly through v-model — without an activator. This is how you open a modal from code: on a server response, from a handler in a table, from a store.

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>

Sizes

The size prop sets the width of the modal: xs (250), sm (350), md (500, the default), lg (700), xl — almost the full width of the screen. A number instead of an alias is an exact width in pixels. The height always adapts to the content, and width and max-width override the size when you need a non-standard grid.

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 modals

The persistent prop turns off closing by a click outside the modal and by the Esc key — the modal can only be closed with the buttons inside it. A click outside shakes the modal, hinting that an answer is still required; the animation is removed by no-click-animation. Take persistent when closing would lose data or when the user has to make a choice.

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>

Scrolling inside the modal

By default long content scrolls together with the whole modal. The scrollable prop pins the header and the buttons and scrolls only the middle — for that the content is assembled from CdsCard: the card becomes the surface of the modal, and the scrolling area is its 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

The fullscreen prop expands the modal to the whole screen: the size props are ignored, the paddings and the rounded corners are removed. It fits document viewing and complex forms on small screens.

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>

Animations

By default the modal grows out of the activator and shrinks back — so you can see where it came from. The transition prop changes the animation: the ready modal-transition-top and modal-transition-bottom slide the modal in from the edge of the screen, and any custom CSS animation works too.

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>

Slots

Slot	Description
activator	The element that opens the modal. The slot props (props) attach the handlers to it
default	The content of the modal. The slot exposes isActive — use it to close the modal without an external variable

Guidelines

Storybook

Scenarios

Delete confirmation

An irreversible action is confirmed with a compact size="sm" modal: the title names the action, the text specifies what exactly will be deleted, the main button repeats the verb from the title. One modal serves the whole list — the selected record is put into it right before opening.

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>

A form in a modal

A short form is opened on top of the list so that the user is not taken away to a separate page. persistent protects what has been typed from an accidental click outside, the submit button shows loading, and "Cancel" is blocked while the request is running. The fields are reset in the after-leave event — after the closing animation, so that the values do not flash in a still visible modal.

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>

An agreement with scrolling

A document that requires an explicit answer is shown in a modal with persistent and scrollable: the text scrolls, and the "Accept" and "Decline" buttons are always in sight. Closing the modal without answering is not possible — the decision is recorded only with the buttons.

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

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	true	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.
fullscreen	boolean | undefined	—	Expands the modal to the whole screen.
height	string | number | undefined	—	Component height
location	Anchor | undefined	'center center'	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	'center center'	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	true	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.
scrollable	boolean | undefined	—	Enables scrolling of the content inside the modal.
scrollStrategy	"none" | "close" | "block" | "reposition" | ScrollStrategyFunction | undefined	'block'	Strategy applied when the component is active and the user scrolls the page.
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Size of the component
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; }) | { component: Component; } | null | undefined	{ component: CdsModalTransition }	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	2400	The z-index value of the component.

Events

Name	Type	Description
afterEnter	[]	Fired after the opening animation of the modal has finished.
afterLeave	[]	Fired after the closing animation of the modal has finished.
update:modelValue	[value: boolean]	Fired when the state of the modal changes.

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.