For a single notification — a save confirmation, for example — CdsToast is enough.

Variations

The message queue

A message is a string or an object with toast props. Add messages to the v-model array: the queue shows them one by one, and the rest wait for their place. The closable prop adds a close button with the close-text label to every toast. Props shared by the toasts — location, timer, status and others — are set right on the queue: they apply to every message. While the browser tab is hidden, auto-closing is paused.

Sandbox Storybook

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

const messages = ref<ToastMessage[]>([]);
let count = 0;

const push = () => {
  messages.value = [...messages.value, `Сообщение №${++count}`];
};
</script>

<template>
  <div class="flex justify-center">
    <CdsButton text="Добавить сообщение" @click="push" />
    <CdsToastQueue v-model="messages" closable />
  </div>
</template>

Limit and overflow

The total-visible prop caps the number of simultaneously visible toasts: a new one takes the place at the edge of the screen and pushes the previous ones aside. The display-strategy prop decides what to do with the extra ones: hold (the default) keeps them in the queue until a place frees up, overflow closes the oldest ones.

Sandbox Storybook

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

const strategy = ref<'hold' | 'overflow'>('hold');
const messages = ref<ToastMessage[]>([]);
let count = 0;

const push = () => {
  messages.value = [...messages.value, { text: `Сообщение №${++count}`, timeout: 8000 }];
};
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsRadioGroup v-model="strategy" label="Стратегия переполнения" direction="horizontal" hide-details>
      <CdsRadio value="hold" label="hold — ждать места" />
      <CdsRadio value="overflow" label="overflow — вытеснять старые" />
    </CdsRadioGroup>

    <CdsButton text="Добавить сообщение" @click="push" />
    <CdsToastQueue v-model="messages" :total-visible="3" :display-strategy="strategy" closable />
  </div>
</template>

The stack

The collapsed prop folds all the toasts except the last one into a compact stack. Hover the cursor — the stack unfolds, and the timers pause while the cursor is inside.

Sandbox Storybook

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

const messages = ref<ToastMessage[]>([]);
let count = 0;

const push = () => {
  messages.value = [
    ...messages.value,
    {
      title: `Событие №${++count}`,
      text: 'Описание события в очереди',
      status: 'success'
    }
  ];
};
</script>

<template>
  <div class="flex justify-center">
    <CdsButton text="Добавить в стопку" @click="push" />
    <CdsToastQueue v-model="messages" collapsed closable :total-visible="10" :timeout="6000" location="bottom right" />
  </div>
</template>

Slots

The slots customize every toast of the queue; each of them receives the item object of the current message.

Slot	Description
header	Header of the toast
text	Text of the toast. Replaces the text of the message
actions	Actions of the toast. props carries an onClick handler that closes the toast
item	Full replacement of the toast. The message props are passed through CdsDefaultsProvider

Scenarios

Background operations

Pass a promise in the message — the toast gets a loading indicator and does not close until the operation is done. The success and error callbacks return the toast props for the result: the status, the text and the auto-close delay.

Sandbox Storybook

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

const messages = ref<ToastMessage[]>([]);

const save = (shouldFail: boolean) => {
  const request = new Promise((resolve, reject) => {
    setTimeout(() => (shouldFail ? reject(new Error('Сервер не ответил')) : resolve(undefined)), 2000);
  });

  messages.value = [
    ...messages.value,
    {
      text: 'Сохраняем изменения…',
      promise: request,
      success: () => ({ status: 'success', text: 'Изменения сохранены', timeout: 4000 }),
      error: (err) => ({ status: 'danger', text: err?.message ?? 'Не удалось сохранить', timeout: 6000 })
    }
  ];
};
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsButton text="Успешное сохранение" @click="save(false)" />
    <CdsButton text="Сохранение с ошибкой" variant="soft" color="brand" @click="save(true)" />
    <CdsToastQueue v-model="messages" :total-visible="3" />
  </div>
</template>

Notification center

The events of the application pile up into a single queue in the corner of the screen: location="bottom right" moves the toasts out of the working area, collapsed hides the older ones in a stack, and closable lets the user close every notification.

Sandbox Storybook

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

const events: ToastMessage[] = [
  { title: 'Новый заказ', text: 'Заказ №1042 ожидает подтверждения', status: 'info' },
  { title: 'Оплата получена', text: 'Счёт №112 оплачен полностью', status: 'success' },
  { title: 'Заканчивается место', text: 'Хранилище заполнено на 90%', status: 'warning' },
  { title: 'Сбой синхронизации', text: 'Не удалось обновить данные. Повторим автоматически', status: 'danger' }
];

const messages = ref<ToastMessage[]>([]);
let next = 0;

const push = () => {
  messages.value = [...messages.value, events[next++ % events.length]];
};
</script>

<template>
  <div class="flex justify-center">
    <CdsButton text="Новое событие" @click="push" />
    <CdsToastQueue v-model="messages" location="bottom right" collapsed closable :total-visible="5" :timeout="8000" />
  </div>
</template>

Controlling the queue

The onDismiss callback of a message receives the reason it was closed — auto, dismissed, overflow or cleared — and the exposed clear() method closes all the toasts and empties the queue.

Sandbox Storybook

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

const queue = ref<InstanceType<typeof CdsToastQueue>>();
const messages = ref<ToastMessage[]>([]);
const log = ref<string[]>([]);
let count = 0;

const push = () => {
  const id = ++count;

  messages.value = [
    ...messages.value,
    {
      text: `Задача №${id} выполнена`,
      status: 'success',
      onDismiss: (reason) => {
        log.value = [`Тост №${id} закрыт: ${reason}`, ...log.value].slice(0, 4);
      }
    }
  ];
};
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <div class="flex gap-2">
      <CdsButton text="Добавить" @click="push" />
      <CdsButton text="Закрыть все" variant="soft" color="neutral" @click="queue?.clear()" />
    </div>

    <div class="h-[96px] text-center">
      <div v-for="line in log" :key="line">{{ line }}</div>
    </div>

    <CdsToastQueue ref="queue" v-model="messages" :total-visible="3" closable />
  </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
closable	string | boolean | undefined	—	Adds a close button to every toast. A string value sets the color of the button.
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
closeText	string | undefined	'$cds.dismiss'	Text of the close button.
collapsed	boolean | undefined	—	Folds the inactive toasts into a stack under the last visible one.
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
displayStrategy	"overflow" | "hold" | undefined	'hold'	Strategy when totalVisible is exceeded: hold — wait until a toast closes, overflow — push the oldest ones out.
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.
gap	string | number | undefined	8	Gap between the toasts, in pixels.
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	readonly ToastMessage[] | undefined	[]	The queue of messages (v-model). A string or an object with toast props.
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.
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.
totalVisible	string | number | undefined	1	Maximum number of simultaneously visible toasts.
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
update:modelValue	[value: ToastMessage[]]	The queue of messages changed.

Slots

Name	Type	Description
actions	{ item: ToastMessage; props: { onClick: () => void; }; }	Slot for the actions of the toast.
header	{ item: ToastMessage; }	Slot for the header of the toast.
item	{ item: ToastMessage; }	Slot that fully replaces the toast. The toast props are passed through CdsDefaultsProvider.
text	{ item: ToastMessage; }	Slot for the text of the toast.

Exposed

Name	Type	Description
clear	() => void	Empties the queue and closes all the visible toasts.