For a stream of events where notifications arrive one after another use CdsToastQueue. A message that has to stay on the page belongs in CdsNotification, and a question that requires a decision from the user — in the CdsModal dialog.

Anatomy

A toast consists of a container and three zones: prepend with the status icon, an avatar or a loading indicator; the content with a heading and text; and the actions zone. The timer prop adds a bar of the remaining time.

Storybook

Variations

Controlling the visibility

Show the toast through v-model or the activator slot — in the second case the component manages its own state. The toast closes automatically after timeout (5000 ms by default); hovering the cursor or focusing inside the toast pauses the countdown, and on touch screens the toast can be swiped away.

Sandbox Storybook

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

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

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsButton text="Открыть через v-model" @click="visible = true" />
    <CdsToast v-model="visible" text="Изменения сохранены" />

    <CdsToast text="Черновик восстановлен">
      <template #activator="{ props }">
        <CdsButton text="Открыть через activator" variant="soft" color="brand" v-bind="props" />
      </template>
    </CdsToast>
  </div>
</template>

Status

The status prop picks the color and the icon by the meaning of the message: info, success, warning, danger, progress. The icon can be replaced by the icon prop or hidden with the value false.

Sandbox Storybook

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

const statuses = ['info', 'success', 'warning', 'danger', 'progress'] as const;
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsButton v-for="status in statuses" :key="status" :color="`status-${status}-surface`" variant="solid">
      {{ status }}
      <CdsToast activator="parent" :status="status" :text="`Уведомление со статусом ${status}`" />
    </CdsButton>
  </div>
</template>

Timer

The timeout prop sets the delay before auto-closing in milliseconds, and -1 turns it off. The bar of the remaining time is enabled by the timer prop (true/top — on top, bottom — at the bottom), reverse-timer flips its direction and timer-color changes its color.

Sandbox Storybook

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

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsToast timer :timeout="4000" text="Тост закроется через 4 секунды">
      <template #activator="{ props }">
        <CdsButton text="Таймер сверху" v-bind="props" />
      </template>
    </CdsToast>

    <CdsToast timer="bottom" reverse-timer :timeout="4000" text="Обратная шкала снизу">
      <template #activator="{ props }">
        <CdsButton text="Таймер снизу" variant="soft" color="brand" v-bind="props" />
      </template>
    </CdsToast>
  </div>
</template>

Position

The location prop puts the toast into one of the six positions: the side (top, bottom) plus the alignment (left, center, right). The toast is rendered above the page content by CdsOverlay.

Sandbox Storybook

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

const locations = ['top left', 'top center', 'top right', 'bottom left', 'bottom center', 'bottom right'] as const;
</script>

<template>
  <div class="grid grid-cols-3 justify-items-center gap-2">
    <CdsButton v-for="location in locations" :key="location" variant="soft" color="neutral">
      {{ location }}
      <CdsToast activator="parent" :location="location" :text="`Тост в позиции ${location}`" />
    </CdsButton>
  </div>
</template>

Content and actions

The heading and the text come from the title and text props, the avatar before the content from prepend-avatar, and loading replaces the icon with a loading indicator. The actions slot adds buttons: inside it they get variant="solid", color="inverse" and size="sm" by default. The vertical layout (vertical) moves the actions below the content.

Sandbox Storybook

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

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsToast
      title="Черновик удалён"
      text="Черновик заявки №42 удалён без возможности восстановления"
      status="warning"
      :timeout="8000"
    >
      <template #activator="{ props }">
        <CdsButton text="С заголовком и действиями" v-bind="props" />
      </template>
      <template #actions="{ isActive }">
        <CdsButton text="Отменить" variant="soft" color="neutral" @click="isActive.value = false" />
      </template>
    </CdsToast>

    <CdsToast
      prepend-avatar="https://i.pravatar.cc/80?img=32"
      title="Ирина Соколова"
      text="Добавила комментарий к заказу"
    >
      <template #activator="{ props }">
        <CdsButton text="С аватаром" variant="soft" color="brand" v-bind="props" />
      </template>
    </CdsToast>

    <CdsToast vertical title="Файл загружается" text="Не закрывайте вкладку до завершения" loading :timeout="-1">
      <template #activator="{ props }">
        <CdsButton text="Вертикальный с загрузкой" variant="soft" color="brand" v-bind="props" />
      </template>
      <template #actions="{ isActive }">
        <CdsButton text="Скрыть" variant="soft" color="neutral" @click="isActive.value = false" />
      </template>
    </CdsToast>
  </div>
</template>

Slots

Slots replace the content coming from props when you need your own markup.

Slot	Description
activator	The element that opens the toast
header	A header across the full width of the toast
prepend	Content before the text. Replaces the icon, the avatar and the loading indicator
title	Heading. Replaces the text from title
text	Text. Replaces the text from text
default	Main content after the text
actions	Actions of the toast

Guidelines

Storybook

Scenarios

Undoing an action

The toast confirms the deletion and gives time to change one's mind: the "Отменить" button in the actions slot brings the document back, and the timer bar shows how much time is left to decide.

Sandbox Storybook

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

const documents = ref(['Договор поставки', 'Счёт №112', 'Акт сверки']);
const visible = ref(false);
const removed = ref<{ name: string; index: number } | null>(null);

const remove = (index: number) => {
  removed.value = { name: documents.value[index], index };
  documents.value.splice(index, 1);
  visible.value = true;
};

const undo = () => {
  if (removed.value) {
    documents.value.splice(removed.value.index, 0, removed.value.name);
  }
  visible.value = false;
};
</script>

<template>
  <div class="flex w-[320px] m-auto flex-col gap-2">
    <div v-for="(name, index) in documents" :key="name" class="flex items-center justify-between">
      {{ name }}
      <CdsButton
        icon="delete"
        variant="soft"
        color="neutral"
        size="sm"
        :aria-label="`Удалить ${name}`"
        @click="remove(index)"
      />
    </div>

    <CdsToast v-model="visible" timer :timeout="6000" :text="removed ? `Документ «${removed.name}» удалён` : ''">
      <template #actions>
        <CdsButton text="Отменить" @click="undo" />
      </template>
    </CdsToast>
  </div>
</template>

A background task

A single toast accompanies the task from the start to the result. While the processing runs, loading shows the indicator and timeout: -1 keeps the notification from disappearing; once it is done the same toast switches to status="success" and closes itself.

Sandbox Storybook

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

const visible = ref(false);
const loading = ref(false);

const generate = () => {
  visible.value = true;
  loading.value = true;

  setTimeout(() => {
    loading.value = false;
  }, 2500);
};
</script>

<template>
  <div class="flex justify-center">
    <CdsButton text="Сформировать отчёт" :disabled="visible && loading" @click="generate" />

    <CdsToast
      v-model="visible"
      :loading="loading"
      :status="loading ? undefined : 'success'"
      :timeout="loading ? -1 : 4000"
      :title="loading ? 'Формируем отчёт' : 'Отчёт готов'"
      :text="loading ? 'Это займёт несколько секунд' : 'Файл сохранён в разделе «Документы»'"
    />
  </div>
</template>

An error with a retry

Do not hide an error automatically: timeout: -1 keeps the toast until the user reacts, and the "Повторить" button in actions runs the request again.

Sandbox Storybook

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

const sending = ref(false);
const failed = ref(false);
const sent = ref(false);
let attempt = 0;

const send = () => {
  sending.value = true;
  failed.value = false;

  setTimeout(() => {
    sending.value = false;
    attempt += 1;

    if (attempt % 2 === 1) {
      failed.value = true;
    } else {
      sent.value = true;
    }
  }, 1500);
};
</script>

<template>
  <div class="flex justify-center">
    <CdsButton text="Отправить заявку" :loading="sending" @click="send" />

    <CdsToast
      v-model="failed"
      status="danger"
      :timeout="-1"
      title="Не удалось отправить заявку"
      text="Сервер не ответил. Попробуйте ещё раз"
    >
      <template #actions>
        <CdsButton text="Повторить" @click="send" />
      </template>
    </CdsToast>

    <CdsToast v-model="sent" status="success" text="Заявка отправлена" />
  </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.
bgColor	string | undefined	—	Background color of the component
closeDelay	string | number | undefined	—	Delay in milliseconds before the component closes. Works only together with open-on-hover.
closeOnBack	boolean | undefined	false	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
collapsed	{ width: number; height: number; } | undefined	—	Collapsed state of a toast in the queue: the size the toast collapses to. Managed by the CdsToastQueue component.
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.)
content	string | number | undefined	—	Content displayed in the component.
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
icon	false | IconValue | undefined	null	Icon before the content. Taken from status by default; false hides the icon.
loading	boolean | undefined	—	Shows a loading indicator instead of the icon.
location	Anchor | null | undefined	'top center'	Position of the element relative to its container, for example "top left", "center", "bottom right".
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.
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.
position	"absolute" | "static" | "fixed" | "relative" | "sticky" | undefined	—	CSS positioning of the component — the value of the position property
prependAvatar	string | undefined	—	Source of the avatar image before the content. Takes priority over the icon.
queueGap	number | undefined	—	Gap between the toasts in the queue, in pixels. Managed by the CdsToastQueue component.
queueIndex	number | undefined	—	Index of the toast in the queue. Managed by the CdsToastQueue component.
reverseTimer	boolean | undefined	—	Reverses the timer bar: it fills up instead of draining.
status	"progress" | "danger" | "success" | "warning" | "info" | undefined	'info'	Semantic status — drives the color and the default icon.
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.
text	string | number | undefined	—	Text displayed in the component.
textColor	string | undefined	—	Text color of the component
theme	string | undefined	—	Component theme
timeout	string | number | undefined	5000	Delay in milliseconds before the toast hides automatically. The value -1 turns auto-closing off.
timer	boolean | "top" | "bottom" | undefined	false	Shows the timer bar until auto-closing: true/top — on top, bottom — at the bottom.
timerColor	string | undefined	—	Color of the timer bar.
title	string | undefined	—	Heading of the toast.
transition	string | boolean | (TransitionProps & { component?: Component | undefined; }) | null | undefined	'cds-toast-transition'	Transition animation
vertical	boolean | undefined	—	Vertical layout: the actions move below the content.
width	string | number | undefined	—	Component width
zIndex	string | number | undefined	2000	The z-index value of the component.

Events

Name	Type	Description
afterEnter	[]	The enter animation finished.
afterLeave	[]	The leave animation finished.
update:modelValue	[value: boolean]	The visibility of the toast changed.

Slots

Name	Type	Description
actions	{ isActive: Ref<boolean, boolean>; }	Slot for the actions of the toast.
activator	{ isActive: boolean; props: Record<string, any>; }	Slot for the element that acts as the activator of the toast.
default	any	Main content of the toast.
header	any	Slot for the full-width header of the toast.
prepend	any	Slot before the content (icon, avatar or loading indicator).
text	any	Text slot.
title	any	Heading slot.

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.