<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. `addToast` returns the message's `id` (its own, or a generated one), which `removeToast` takes; `close` fires on the container with the message once a toast has left.
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-alert. A field's hint or error message belongs to the field (c-messageunder a control of your own).
Closing
A toast with a close button can also be swiped away: drag it left or right and let go past a third of its width, or flick it. A shorter drag springs back, and a vertical drag scrolls the page as usual. Custom and indeterminate toasts have no close button and can't be swiped.
A timed toast waits while the pointer hovers over it or presses it, and carries on with the time it had left. When a toast arrives or leaves, the others glide to their new places.
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.
position places the stack: bottom (the default), bottom-start,
bottom-end, top, top-start or top-end, start being the left edge and
end the right. contained keeps the stack inside its nearest positioned
ancestor instead of the viewport, for in-container notifications. A contained
stack lives inside your page's stacking contexts, so it does not carry the
above-modal guarantee. The 3.x vertical, horizontal and absolute still
work until 5.0; position and contained win when set.
Accessibility
Each toast is a role="alert" live region announced assertively when it
appears. Keep messages short; use persistent for messages the user must
close themselves.
Swiping is a shortcut, never the only way: every swipeable toast has its close button. On a touch screen, pressing and holding a toast keeps it up for as long as the user needs to read it.
Styling
Each toast's parts are forwarded from the container as toast-*:
c-toasts::part(toast-root) is a toast's box, and toast-item,
toast-badge, toast-content, toast-close, toast-custom and
toast-progress its pieces.
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';
type CToastsElement = {
addToast: (message: ToastMessage) => void;
} & HTMLElement;
interface ToastMessage {
duration?: number;
heading?: string;
message: string;
persistent?: boolean;
progress?: boolean;
type?: 'error' | 'info' | 'success' | 'warning';
}
const toasts = useTemplateRef<CToastsElement>('toasts');
const notify = (type: 'error' | 'success') => {
toasts.value?.addToast({
heading: type === 'success' ? 'Saved' : 'Upload failed',
message:
type === 'success'
? 'Your changes have been saved.'
: 'The file could not be uploaded.',
progress: true,
type,
});
};
</script>
<template>
<div class="example-row">
<c-select v-model="position" label="Position" hide-message>
<c-option name="Top start" value="top-start">Top start</c-option>
<c-option name="Top" value="top">Top</c-option>
<c-option name="Top end" value="top-end">Top end</c-option>
<c-option name="Bottom start" value="bottom-start">Bottom start</c-option>
<c-option name="Bottom" value="bottom">Bottom</c-option>
<c-option name="Bottom end" value="bottom-end">Bottom end</c-option>
</c-select>
<c-button @click="notify()">Show toast</c-button>
<c-toasts ref="toasts" :position />
</div>
</template>
<script setup lang="ts">
import { ref, useTemplateRef } from 'vue';
type CToastsElement = {
addToast: (message: ToastMessage) => void;
} & HTMLElement;
interface ToastMessage {
duration?: number;
heading?: string;
message: string;
persistent?: boolean;
progress?: boolean;
type?: 'error' | 'info' | 'success' | 'warning';
}
const toasts = useTemplateRef<CToastsElement>('toasts');
const position = ref('bottom');
const notify = () => {
toasts.value?.addToast({
heading: 'Notification',
message: `Placed at ${position.value}.`,
progress: true,
type: 'info',
});
};
</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. `addToast` returns the message's `id` (its own, or a generated one), which `removeToast` takes; `close` fires on the container with the message once a toast has left.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
contained | contained | boolean | — | Keep the stack inside its nearest positioned ancestor instead of the viewport, for in-container notifications. Such a stack is not guaranteed to paint above an open modal. |
position | position | CToastsPosition | — | Where the stack sits in the viewport, or in its container when `contained`: `bottom` (unless set), `bottom-start`, `bottom-end`, `top`, `top-start` or `top-end`. Toasts slide in from the top or bottom edge. |
absolute deprecated | absolute | boolean | false | Deprecated. Use `contained`. Places the stack in its nearest positioned ancestor instead of the viewport, for in-container notifications. Such a stack is not guaranteed to paint above an open modal. |
horizontal deprecated | horizontal | CToastsHorizontal | 'center' | Deprecated. Use `position`. Where the stack sits across the viewport, or across its container under `absolute`. |
vertical deprecated | vertical | CToastsVertical | 'bottom' | Deprecated. Use `position`. The edge the stack is anchored to; toasts slide in from it. |
Events
| Event | Detail | Description |
|---|---|---|
close | CToastMessage | Fired once a toast has left (closed by its close button, a swipe, the timer or `removeToast`), carrying its message with the `id` it was shown under. |
Methods
| Method | Signature | Description |
|---|---|---|
addToast | (message: CToastMessage): string | undefined | Show a message as a toast and return its `id` — the message's own, or a generated one — for `removeToast`. A second `custom` message while one is shown is refused, and returns `undefined`. |
removeToast | (id: string) | Close the toast with this `id`, the one `addToast` returned. |
Slots
| Slot | Description |
|---|---|
default | Content of a custom toast message, projected into the single `custom`-flagged 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 toasts stack in |
toast-root | A toast's outer box: the inverted-surface pill carrying the shadow |
toast-custom | Wrapper shown for a custom message in place of the standard row |
toast-content | A toast's message body holding the heading and text, or the slotted custom content |
toast-item | Row layout of a standard toast: status badge, message body and close button |
toast-badge | The circular tinted badge holding a toast's status icon |
toast-close | A toast's close button (icon-only, or labelled when the message sets `closeText`) |
toast-progress | The track of a toast's auto-close progress bar |
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';CToastsPosition
Where the toast stack sits: the edge it is anchored to, then its alignment along it — `start` is the left, `end` the right — or centred.
export type CToastsPosition =
| 'bottom-end'
| 'bottom-start'
| 'bottom'
| 'top-end'
| 'top-start'
| 'top';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 internal `c-toast`, and the detail of `c-toasts`' `close` event.
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;
/** Optional heading rendered above the message. */
heading?: string;
/**
* Identifier for `removeToast`. `addToast` generates one when it is
* omitted, and returns it either way.
*/
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;
/** 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';