C&C Docs
Log in

cnc-toast

A top-layer notification stack driven by toast window events. The newest message flies in from the nearest viewport edge and stays in front; hover the stack to expand every message and pause auto-dismissal. The card treatment follows the default notification language with layered shadows, compact typography, and concentric status indicators.

Quick start

Put one <cnc-toast> in the application shell — this page already has one, which is why the buttons below work without adding another — then raise messages from anywhere by dispatching a toast event on window. 

<!-- once, in the application shell -->
<cnc-toast placement="bottom-right"></cnc-toast>

<!-- anywhere at all -->
window.dispatchEvent(new CustomEvent('toast', {
  detail: { tone: 'success', title: 'Saved', message: 'Your changes are live.' },
}))

One instance per page

cnc-toast is a page-level singleton because it consumes a global window event. The first connected instance owns the event listener. Additional instances remain inactive and issue a console warning. If the owner is removed, the next connected instance takes over automatically.

The toast event

The widget emits nothing. It LISTENS, on window, for a toast event, and every field below is a key on that event's detail. Because the listener is on the window rather than the element, any code anywhere on the page can raise a toast without holding a reference to the widget — which is the whole point of the singleton.

Detail key Default Purpose
tone primary success, warning, danger, info or primary. Chooses the default icon and title together. kind is accepted as an alias here, which is NOT the same kind as the element's card design.
title per tone Card heading. Defaults to the tone's name — "Success", "Warning", "Failed", "Information", "Notification".
message empty Body text under the title.
icon per tone Overrides the tone's icon with any cnc-icon name.
iconKind per icon-kinds Overrides the icon treatment for this message only.
duration the stack's delay Auto-dismiss time in milliseconds for this message. delay is accepted as a compatibility alias.

Usage

<cnc-toast kind="soft" size="md" placement="top-right" offset="88" visible="3"></cnc-toast>

window.dispatchEvent(new CustomEvent('toast', {
  detail: {
    tone: 'success',
    title: 'Changes published',
    message: 'Your workspace is live.',
    icon: 'fa/check-circle'
  }
}))

detail.kind remains a compatibility alias for detail.tone. The event tone is separate from the host kind, which selects the toast design. Icon kinds map to soft → ring, filled → outline, and outline → soft. Provide detail.iconKind to override the mapping for one message.

Usage guidance

Put ONE cnc-toast in the application shell and never in a page or a component. Additional instances go inactive and warn to the console; a toast placed on a page also disappears with it, taking any message raised on the way out. Since the trigger is a window event, nothing needs the element in scope to use it.

A toast is for something the user does not need to act on: it appears, it auto-dismisses, and it may never be read. Anything that must be acknowledged belongs in a cnc-modal, and anything that must persist until resolved belongs in a cnc-alert on the page itself. In particular, do not report a failure the user has to do something about with a toast that removes itself after four seconds.

Watch the two meanings of kind. On the element it selects the card design (soft, filled, outline); in the event detail it is an alias for tone and selects the status. Prefer tone in the detail so the distinction stays visible at the call site.

← Back to Widgets