Toast

<caos-toast>

a transient outcome notice

Nowhere yet — this piece is not offered to a page.

Inputs

Name	Attribute	Description	Type	Default	Required
intent	intent, markup only	What kind of outcome this is: info, success, warning or danger. It colours the leading edge and the glyph from the semantic tokens, and danger is also what makes the notice assertive to a screen reader rather than polite. error is accepted as a spelling of danger.	text — one of info, success, warning, danger, error	info	Optional
duration	duration, markup only	Milliseconds to stay before dismissing itself. There is NO ambient default: leave it unset (or set it to zero) and no timer ever runs, so the toast stays until it is dismissed. The timer pauses while the toast is hovered or holds focus, and resumes when it is left.	number	none declared	Optional

Events

Name	When it fires	What it carries
caos-toast-dismiss	The dismiss control is pressed, the timer elapses, or something calls dismiss(). It is cancelable, and unlike the overlay this piece does act on its own: if nobody prevents the event, the toast removes itself.	nothing

Slots

Name	What goes in it
the default slot	The message. One sentence about something that has already happened.
action	An optional control beside the message — an Undo, typically. The toast draws it and nothing more; what pressing it does belongs to whatever raised the toast.

Styling hooks

Design token	What it controls
--caos-color-surface	The body fill, which stays neutral at every intent so the message stays legible.
--caos-color-border	The edge of the notice.
--caos-color-info	The leading accent and glyph at the default intent.
--caos-color-success	The leading accent and glyph at intent success.
--caos-color-warning	The leading accent and glyph at intent warning.
--caos-color-danger	The leading accent and glyph at intent danger.
--caos-color-text	The message text.
--caos-color-text-muted	The resting colour of the dismiss control.
--caos-shadow-float	The one elevation reserved for pieces that float.
--caos-radius	The corner radius of the notice.
--caos-radius-sm	The corner radius of the dismiss control.
--caos-focus-ring	The ring on the dismiss control when it is reached by keyboard.
--caos-space-3	The gap between glyph, message and controls, and the vertical padding.
--caos-space-4	The horizontal padding.
--caos-font	The typeface the message is set in.

Methods

Name	Description	Arguments
dismiss()	Dismiss it from code — the same path the close control and the timer take, so a host that cancels the event cancels every route to dismissal at once.	takes none

Readable state

Nothing on this piece can be read back.

Styling parts

Part	Which piece of it	When it is there
::part(toast)	the toast	Always
::part(icon)	the intent glyph	Always
::part(content)	the message	Always
::part(dismiss)	the dismiss control	Always

When to use it

The outcome of something that has already happened, needs no answer, and can be missed without harm. Nothing in a toast should be the only place a person could have learned something: it can be dismissed in a keystroke, and if a duration is set it removes itself.

What to use instead

• NoticeBanner — The notice MUST NOT disappear — it needs a decision, or it states a condition of the page that is still true after the person has read it.
• ValidationSummary — A save was refused and the person has specific fields to go and fix.
• ProgressBar — The thing is still happening rather than finished.
• ToastStack — A screen raises several of these and they need somewhere to accumulate and a cap.

Accessibility

The notice is a live region on its own: role=“status” for info, success and warning, and role=“alert” for danger and error, so a failure interrupts and the rest does not. The dismiss control is a real button with an accessible name, and the auto-dismiss timer pauses while the toast is hovered or holds focus so a reader is not raced. What is left to the author: the message has to stand alone when read out of context, and anything a person must act on does not belong in a piece that removes itself.

Examples

The four intents

Every outcome colour the toast has. The danger one is also the only one announced assertively, which is a difference you cannot see in the picture.

{
  "id": "example",
  "section": "The four intents",
  "columns": 1,
  "items": [
    {
      "id": "toast_1",
      "type": "component",
      "key": "toast",
      "inputs": {
        "intent": "info"
      },
      "children": [
        "Totals were refreshed from the account."
      ]
    },
    {
      "id": "toast_2",
      "type": "component",
      "key": "toast",
      "inputs": {
        "intent": "success"
      },
      "children": [
        "Order saved."
      ]
    },
    {
      "id": "toast_3",
      "type": "component",
      "key": "toast",
      "inputs": {
        "intent": "warning"
      },
      "children": [
        "Two line items have no amount."
      ]
    },
    {
      "id": "toast_4",
      "type": "component",
      "key": "toast",
      "inputs": {
        "intent": "danger"
      },
      "children": [
        "The order could not be sent."
      ]
    }
  ]
}

<caos-toast intent="info">Totals were refreshed from the account.</caos-toast>
<caos-toast intent="success">Order saved.</caos-toast>
<caos-toast intent="warning">Two line items have no amount.</caos-toast>
<caos-toast intent="danger">The order could not be sent.</caos-toast>

With an action

The action slot holding an Undo beside the message. The toast draws the control; what pressing it does is for the caller to decide, because the toast has no idea what it reported.

{
  "id": "example",
  "section": "With an action",
  "columns": 1,
  "items": [
    {
      "id": "toast_1",
      "type": "component",
      "key": "toast",
      "inputs": {
        "intent": "success"
      },
      "children": [
        "Line item removed.",
        {
          "id": "button_2",
          "type": "component",
          "key": "button",
          "inputs": {
            "variant": "ghost",
            "size": "sm"
          },
          "slot": "action",
          "children": [
            "Undo"
          ]
        }
      ]
    }
  ]
}

<caos-toast intent="success">
  Line item removed.
  <caos-button slot="action" variant="ghost" size="sm">Undo</caos-button>
</caos-toast>

Dismissing itself

The opt-in timer: this one leaves after six seconds, and the timer stops for as long as the pointer is over it or a control inside it holds focus. Reset the example to bring it back.

{
  "id": "example",
  "section": "Dismissing itself",
  "columns": 1,
  "items": [
    {
      "id": "toast_1",
      "type": "component",
      "key": "toast",
      "inputs": {
        "intent": "info",
        "duration": 6000
      },
      "children": [
        "Draft saved. This notice leaves on its own."
      ]
    }
  ]
}

<caos-toast intent="info" duration="6000">Draft saved. This notice leaves on its own.</caos-toast>