CSC Design System v4.0.1
VueFlavour Vue React Angular TypeScript
Flavour Vue React Angular TypeScript
PrimaryCSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
CSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
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';