CSC Design System v4
VueFlavour Vue React Angular TypeScriptPrimaryCSC UI ColorsPrimarySecondaryAccentCustom ColorsRedOrangeGreenBluePurplePink
Guides Getting started Customization Data visualization Migration guide Componentsc-accordionc-alertc-autocompletec-badgec-breadcrumbc-buttonc-button-groupc-cardc-checkboxc-color-pickerc-csc-logoc-data-tablec-date-pickerc-dividerc-file-uploadc-iconc-icon-buttonc-linkc-listc-loaderc-login-buttonsc-login-cardc-mainc-menuc-messagec-modalc-navigation-buttonc-number-fieldc-otp-inputc-pagec-paginationc-popoverc-progress-barc-progress-circlec-radio-groupc-selectc-side-navigationc-sliderc-spinnerc-statusc-stepsc-switchc-tablec-tabsc-tagsc-text-fieldc-time-pickerc-toastsc-toolbarc-tooltipc-tree-select

<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-message under 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

Basic
Vue React Angular TypeScript
<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>
Placement
Vue React Angular TypeScript
<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

PropertyAttributeTypeDefaultDescription
containedcontainedboolean— 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.
positionpositionCToastsPosition— 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 absolutebooleanfalse 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 horizontalCToastsHorizontal'center' Deprecated. Use `position`. Where the stack sits across the viewport, or across its container under `absolute`.
vertical deprecated verticalCToastsVertical'bottom' Deprecated. Use `position`. The edge the stack is anchored to; toasts slide in from it.

Events

EventDetailDescription
closeCToastMessageFired 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

MethodSignatureDescription
addToast(message: CToastMessage): string | undefinedShow 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

SlotDescription
defaultContent 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.

PartDescription
rootThe grid container the toasts stack in
toast-rootA toast's outer box: the inverted-surface pill carrying the shadow
toast-customWrapper shown for a custom message in place of the standard row
toast-contentA toast's message body holding the heading and text, or the slotted custom content
toast-itemRow layout of a standard toast: status badge, message body and close button
toast-badgeThe circular tinted badge holding a toast's status icon
toast-closeA toast's close button (icon-only, or labelled when the message sets `closeText`)
toast-progressThe 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';