Skip to content
Kimenpre-v1documentation home
Color scheme

ki-toast

A short, transient message about something the person just did, shown without blocking the page. It leaves on its own after its time, which stops while the person points at the toaster, works inside it or is away from the page. Raise it into a ki-toaster.

Theme for this example
Color scheme for this example
Workspace settings are up to date.
<ki-toast tone="success" heading="Changes saved" duration="0">
Workspace settings are up to date.
</ki-toast>

tone picks the icon and its ink, and the live-region urgency; the surface stays the same.

Theme for this example
Color scheme for this example
Sync complete. Storage is almost full. The file is larger than 20 MB.
<ki-toast tone="info" duration="0">Sync complete.</ki-toast>
<ki-toast tone="warning" duration="0">Storage is almost full.</ki-toast>
<ki-toast tone="danger" heading="Upload failed">The file is larger than 20 MB.</ki-toast>

One ghost ki-button size="sm": its click runs, then the toast leaves. A toast with an action never leaves on its own.

Theme for this example
Color scheme for this example
The conversation moved to your archive. Undo
<ki-toast heading="Message archived">
The conversation moved to your archive.
<ki-button slot="action" variant="ghost" size="sm">Undo</ki-button>
</ki-toast>

When to use: confirm an action that happened elsewhere on screen ("Changes saved", "Link copied"), report a background result ("Export ready"), or offer a quick undo. Raise it into a ki-toaster, in markup or with its show() method; express urgency with tone.

When not to use: anything the person must read or act on to continue belongs to ki-dialog; form validation belongs to the field's error text; a lasting condition of the page belongs to ki-alert, which stays inline. Assistive technology note: a toast announces as it appears, so append it when the event happens; a toast present at initial page load is exposed with its role but its announcement is not guaranteed. The heading and the message are the whole announcement: the icon, the action and the dismiss button stay outside the live region.

Properties & attributes

AttributePropertyTypeDefaultDescription
dismiss-labeldismissLabelstring'Dismiss'Accessible name of the dismiss button. Override for localization; the default English word is the component's only built-in text. When to use: whenever the document language is not English. When NOT to use: do not put the message here; use the default slot.
dismisseddismissedbooleanfalseReflected state: true once the toast has left. The timer, the dismiss button, Escape and the action set it; the page may set or clear it. While true the host stays in the document but renders nothing and leaves the accessibility tree. Clearing it shows the toast again with its full time. When to use: show a toast again, or close it from the page. When NOT to use: do not read programmatic changes as dismissals; ki-dismiss reports only the timer and the person.
dismissibledismissiblebooleantrueShows the dismiss button, a ghost ki-icon-button named by dismiss-label. Escape still dismisses a focused toast without it. When to use: keep it on unless the toast leaves on its own and the page offers no other way to read it again. When NOT to use: do not turn it off on a toast that waits for the person.
durationdurationnumber | undefined–How long the toast stays, in milliseconds, before it leaves on its own; 0 keeps it until it is dismissed. Ignored (treated as 0) when the toast holds an action or its tone is danger. Unset, or not a finite number of zero or more, it is 5000. The time stops while the pointer rests on the toaster, while focus is inside it, or while the page is hidden, and continues with what was left. Changing it restarts the time. When to use: give a longer message more time. When NOT to use: do not shorten it below what a person needs to read the message.
headingheadingstring | undefined–Optional bold first line, inside the live region. Empty strings render no heading. It is a strong element, never a document heading. When to use: a short label for the event ("Changes saved"). When NOT to use: do not use it for page structure.
queuedqueuedbooleanfalseOutput-only state written by an enclosing ki-toaster: true while the toast waits for a place. A queued toast renders nothing, is absent from the accessibility tree and its time does not run. Authors do not set it; the toaster overwrites it.
tonetone"danger" | "info" | "neutral" | "success" | "warning" | string & {}'neutral'Picks the icon and its ink, and the live-region urgency: danger exposes role="alert" and never leaves on its own; neutral, info, success, warning, absent and unrecognized values expose role="status". The surface and the text look the same in every tone. Unknown values render neutral. When to use: choose the tone that describes what happened. When NOT to use: do not use tone for emphasis; a lasting failure belongs in ki-alert.

Events

EventDetail typeDescription
ki-dismissCustomEvent<KiToastDismissDetail>Fired once when the toast leaves because its time ran out (reason: "timeout"), the person used the dismiss button ("button"), pressed Escape inside it ("escape") or activated its action ("action"), after it is hidden and focus has been handed on. Not cancelable. When to use: remove the element, or record that the message was seen. When NOT to use: do not expect it for programmatic dismissed changes.

Slots

SlotDescription
(default)Message text. It lives inside the live-region boundary.
actionAt most one action, as a ki-button size="sm" variant="ghost". Its own click handler runs, then the toast leaves (reason: "action"). A toast holding an action never leaves on its own. When NOT to use: a response the person cannot skip belongs in ki-dialog.

CSS parts

PartDescription
actionWrapper around the action slot, rendered only when it holds content.
dismissThe dismiss ki-icon-button, rendered only when dismissible.
headingOptional bold first line, rendered only when non-empty.
iconThe tone icon, drawn by the component in the tone's ink.
messageMessage wrapper around the default slot.
toastThe flat surface: fill, image, edge, radius, padding, elevation and backdrop filter.

CSS custom properties

The public styling contract of ki-toast: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-density-space-scaleMultiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip).
--ki-motion-distance-smMotion travel distance sm (4px): small slide/settle offsets.
--ki-motion-duration-medium-1M3 md.sys.motion.duration.medium1 (250ms). onmars: MarsUI moderate step (240ms, 2x the 120ms base).
--ki-motion-easing-outDecelerating interaction transition easing curve.
--ki-toast-backdrop-filterfilter used by the toast component behind its surface, taken whole: none by default; a theme may blur here (document 2, rule 6; issue #342).
--ki-toast-bgcolor used by the toast component for its flat raised surface (issue #353: surface-raised, the deprecated alias of surface.s1, so the step itself).
--ki-toast-bg-imageimage used by the toast component over its background color: none by default; a theme may paint a gradient here (document 2, rule 6).
--ki-toast-bordercolor used by the toast component for its hairline edge (issue #353).
--ki-toast-border-widthdimension used by the toast component for its hairline edge.
--ki-toast-danger-iconcolor used by the toast component for the danger tone icon: the tone lives in the icon alone (issue #353).
--ki-toast-fgcolor used by the toast component for the heading ink (issue #353).
--ki-toast-gapdimension used by the toast component between icon, text, action and dismiss button (issue #353: 12px).
--ki-toast-heading-font-familyFont family for the toast heading (document 2, rule 6; issue #347). Override it to give toasts their own heading typeface.
--ki-toast-icon-sizedimension used by the toast component for the tone icon.
--ki-toast-info-iconcolor used by the toast component for the info tone icon: the tone lives in the icon alone (issue #353).
--ki-toast-message-fgcolor used by the toast component for the message ink (issue #353).
--ki-toast-neutral-iconcolor used by the toast component for the neutral tone icon: the tone lives in the icon alone (issue #353).
--ki-toast-paddingdimension used by the toast component for its padding (issue #353: 12px).
--ki-toast-radiusdimension used by the toast component for its corners (issue #353: 16px).
--ki-toast-shadowshadow used by the toast component for its elevation (issue #353: e4). The only theme-controlled shadow in the toast's box-shadow (document 2, rule 6).
--ki-toast-success-iconcolor used by the toast component for the success tone icon: the tone lives in the icon alone (issue #353).
--ki-toast-warning-iconcolor used by the toast component for the warning tone icon: the tone lives in the icon alone (issue #353).
--ki-toast-widthdimension used by the toast component for the widest a toast gets (issue #353: 22.5rem).
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-line-height-body-2semantic dimension for typography line height body 2.
--ki-typography-line-height-parasemantic dimension for typography line height para.
--ki-typography-size-body-1semantic dimension for typography size body 1.
--ki-typography-size-body-2semantic dimension for typography size body 2.
--ki-typography-weight-body-semiboldsemantic font weight for typography weight body semibold.

danger toasts expose role="alert", every other tone role="status"; no toast moves focus. Only the heading and the message are announced. The time stops while the pointer rests on the toaster, while focus is inside it or while the page is hidden (WCAG 2.2.1); Escape dismisses a focused toast. dismiss-label is the only built-in word: localize it whenever the document language is not English.

Open ki-toast in Storybook