<c-toasts>
Toasts are passive, transient notifications — operation results, background progress — stacked and managed by a single `c-toasts` container via its `addToast` / `removeToast` methods.
Usage
When to use
- Confirming a completed action (saved, sent, deleted).
- Non-blocking errors and warnings the user can act on later.
When not to use
- Anything requiring a decision before continuing — use
c-modal. - Persistent page-level status — use
c-alertorc-message.
Placement and modals
Place the default (fixed-position) c-toasts as a direct child of body or
c-main. So placed, toasts are guaranteed to paint above any open modal
and stay fully interactive — close buttons and hover-to-pause keep working
while a modal blocks the rest of the page.
The absolute variant positions the stack inside a container for
in-container notifications. It lives inside your page's stacking contexts,
so it does not carry the above-modal guarantee.
Accessibility
Each toast is a role="alert" live region announced assertively when it
appears. Keep messages short; use persistent for messages the user must
dismiss themselves.
Examples
<template>
<div class="example-row">
<c-button @click="notify('success')">Show success toast</c-button>
<c-button @click="notify('error')">Show error toast</c-button>
<c-toasts ref="toasts" />
</div>
</template>
<script setup lang="ts">
import { useTemplateRef } from 'vue';
interface ToastMessage {
duration?: number;
message: string;
persistent?: boolean;
progress?: boolean;
title?: string;
type?: 'error' | 'info' | 'success' | 'warning';
}
type CToastsElement = HTMLElement & {
addToast: (message: ToastMessage) => void;
};
const toasts = useTemplateRef<CToastsElement>('toasts');
const notify = (type: 'error' | 'success') => {
toasts.value?.addToast({
type,
title: type === 'success' ? 'Saved' : 'Upload failed',
message:
type === 'success'
? 'Your changes have been saved.'
: 'The file could not be uploaded.',
progress: true,
});
};
</script>
<template>
<div class="example-row">
<c-select v-model="vertical" label="Vertical" hide-details>
<c-option name="Bottom" value="bottom">Bottom</c-option>
<c-option name="Top" value="top">Top</c-option>
</c-select>
<c-select v-model="horizontal" label="Horizontal" hide-details>
<c-option name="Left" value="left">Left</c-option>
<c-option name="Center" value="center">Center</c-option>
<c-option name="Right" value="right">Right</c-option>
</c-select>
<c-button @click="notify()">Show toast</c-button>
<c-toasts ref="toasts" :horizontal="horizontal" :vertical="vertical" />
</div>
</template>
<script setup lang="ts">
import { ref, useTemplateRef } from 'vue';
interface ToastMessage {
duration?: number;
message: string;
persistent?: boolean;
progress?: boolean;
title?: string;
type?: 'error' | 'info' | 'success' | 'warning';
}
type CToastsElement = HTMLElement & {
addToast: (message: ToastMessage) => void;
};
const toasts = useTemplateRef<CToastsElement>('toasts');
const vertical = ref('bottom');
const horizontal = ref('center');
const notify = () => {
toasts.value?.addToast({
type: 'info',
title: 'Notification',
message: `Placed at ${vertical.value} ${horizontal.value}.`,
progress: true,
});
};
</script>
<template>
<div>
<!-- Toasts are normally created by c-toasts, which renders a c-toast for
each message. A persistent message can be shown standalone. -->
<c-toast :message.prop="message" />
</div>
</template>
<script setup lang="ts">
const message = {
id: 'example',
title: 'Saved',
message: 'Your changes have been saved.',
type: 'success',
persistent: true,
};
</script>
API reference
<c-toasts>
Toasts are passive, transient notifications — operation results, background progress — stacked and managed by a single `c-toasts` container via its `addToast` / `removeToast` methods.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
absolute | absolute | boolean | false | Use absolute positioning |
horizontal | horizontal | CToastsHorizontal | 'center' | Horizontal position |
vertical | vertical | CToastsVertical | 'bottom' | Vertical position |
Methods
| Method | Signature | Description |
|---|---|---|
addToast | (message: CToastMessage) | Add a new message |
removeToast | (id: string) | Remove a message by id (id should be specified in the addToast params) |
Slots
| Slot | Description |
|---|---|
default | Content of a custom toast message, projected into the single `custom`-flagged c-toast |
CSS parts
Style from outside with c-toasts::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The grid container the toast items stack in |
Types
Importable from the package root: import type { … } from '@cscfi/csc-ui'
CToastsHorizontal
Horizontal placement of the toast stack.
export type CToastsHorizontal = 'center' | 'left' | 'right';CToastsProps
export interface CToastsProps {
/**
* Use absolute positioning
*
* @seeded from csc-ui — verify
*/
absolute?: boolean;
/**
* Horizontal position
*
* @seeded from csc-ui — verify
*/
horizontal?: CToastsHorizontal;
/**
* Vertical position
*
* @seeded from csc-ui — verify
*/
vertical?: CToastsVertical;
}CToastsVertical
Vertical placement of the toast stack.
export type CToastsVertical = 'bottom' | 'top';CToastMessage shared
A toast notification: the argument to `c-toasts`' `addToast` method, rendered by the composed `c-toast` child.
export interface CToastMessage {
/** Label of the toast's close button. */
closeText?: string;
/** Render the slotted custom content instead of `message`. */
custom?: boolean;
/** How long the toast stays visible, in milliseconds. Defaults to 6000. */
duration?: number;
/** Identifier used to remove the toast via `removeToast`. */
id?: string;
/** Show an indeterminate progress bar instead of the countdown. */
indeterminate?: boolean;
/** The message text. */
message: string;
/** Keep the toast visible until it is explicitly closed. */
persistent?: boolean;
/** Show a progress bar counting down the toast's remaining duration. */
progress?: boolean;
/** Optional title rendered above the message. */
title?: string;
/** Status type of the toast. Defaults to `info`. */
type?: CToastType;
}CToastType shared
Status type of a toast notification, selecting the accent colour and icon.
export type CToastType = 'error' | 'info' | 'success' | 'warning';<c-toast>
A single toast notification, rendered and managed by c-toasts
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
message | message | | null | Messages |
Events
| Event | Detail | Description |
|---|---|---|
close | CToastMessage | null | Fired once the toast's leave transition has finished (after a manual dismiss or the auto-close timer), carrying the dismissed toast's message object. |
Methods
| Method | Signature | Description |
|---|---|---|
closeToast | () |
Slots
| Slot | Description |
|---|---|
default | Custom toast content, shown when the message is flagged `custom` |
CSS parts
Style from outside with c-toast::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The toast's outer box: the inverted-surface pill carrying the shadow |
custom | Wrapper shown for custom messages in place of the standard item layout |
content | The message body holding the title and text, or the slotted custom content |
item | Row layout of a standard toast: status badge, message body and dismiss button |
badge | The circular tinted badge holding the status icon |
dismiss | The dismiss button (icon-only, or labelled when the message sets `closeText`) |
progress | The track of the auto-close progress bar |
Types
Importable from the package root: import type { … } from '@cscfi/csc-ui'
CToastProps
export interface CToastProps {
/**
* Messages
*
* @seeded from csc-ui — verify
*/
message?: CToastMessage | null;
}