ki-toast
@kimen/elements/ki-toast- Source
- Agent reference
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.
<ki-toast tone="success" heading="Changes saved" duration="0">Workspace settings are up to date.</ki-toast>Examples
Section titled “Examples”tone picks the icon and its ink, and the live-region urgency; the surface
stays the same.
<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>Action
Section titled “Action”One ghost ki-button size="sm": its click runs, then the toast leaves. A
toast with an action never leaves on its own.
<ki-toast heading="Message archived">The conversation moved to your archive.<ki-button slot="action" variant="ghost" size="sm">Undo</ki-button></ki-toast>API reference
Section titled “API reference”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
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
dismiss-label | dismissLabel | string | '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. |
dismissed | dismissed | boolean | false | Reflected 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. |
dismissible | dismissible | boolean | true | Shows 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. |
duration | duration | number | 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. |
heading | heading | string | 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. |
queued | queued | boolean | false | Output-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. |
tone | tone | "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
| Event | Detail type | Description |
|---|---|---|
ki-dismiss | CustomEvent<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
| Slot | Description |
|---|---|
| (default) | Message text. It lives inside the live-region boundary. |
action | At 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
| Part | Description |
|---|---|
action | Wrapper around the action slot, rendered only when it holds content. |
dismiss | The dismiss ki-icon-button, rendered only when dismissible. |
heading | Optional bold first line, rendered only when non-empty. |
icon | The tone icon, drawn by the component in the tone's ink. |
message | Message wrapper around the default slot. |
toast | The 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.
| Token | Description |
|---|---|
--ki-density-space-scale | Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). |
--ki-motion-distance-sm | Motion travel distance sm (4px): small slide/settle offsets. |
--ki-motion-duration-medium-1 | M3 md.sys.motion.duration.medium1 (250ms). onmars: MarsUI moderate step (240ms, 2x the 120ms base). |
--ki-motion-easing-out | Decelerating interaction transition easing curve. |
--ki-toast-backdrop-filter | filter 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-bg | color 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-image | image 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-border | color used by the toast component for its hairline edge (issue #353). |
--ki-toast-border-width | dimension used by the toast component for its hairline edge. |
--ki-toast-danger-icon | color used by the toast component for the danger tone icon: the tone lives in the icon alone (issue #353). |
--ki-toast-fg | color used by the toast component for the heading ink (issue #353). |
--ki-toast-gap | dimension used by the toast component between icon, text, action and dismiss button (issue #353: 12px). |
--ki-toast-heading-font-family | Font family for the toast heading (document 2, rule 6; issue #347). Override it to give toasts their own heading typeface. |
--ki-toast-icon-size | dimension used by the toast component for the tone icon. |
--ki-toast-info-icon | color used by the toast component for the info tone icon: the tone lives in the icon alone (issue #353). |
--ki-toast-message-fg | color used by the toast component for the message ink (issue #353). |
--ki-toast-neutral-icon | color used by the toast component for the neutral tone icon: the tone lives in the icon alone (issue #353). |
--ki-toast-padding | dimension used by the toast component for its padding (issue #353: 12px). |
--ki-toast-radius | dimension used by the toast component for its corners (issue #353: 16px). |
--ki-toast-shadow | shadow 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-icon | color used by the toast component for the success tone icon: the tone lives in the icon alone (issue #353). |
--ki-toast-warning-icon | color used by the toast component for the warning tone icon: the tone lives in the icon alone (issue #353). |
--ki-toast-width | dimension used by the toast component for the widest a toast gets (issue #353: 22.5rem). |
--ki-typography-family-body | semantic font family for typography family body. |
--ki-typography-line-height-body-2 | semantic dimension for typography line height body 2. |
--ki-typography-line-height-para | semantic dimension for typography line height para. |
--ki-typography-size-body-1 | semantic dimension for typography size body 1. |
--ki-typography-size-body-2 | semantic dimension for typography size body 2. |
--ki-typography-weight-body-semibold | semantic font weight for typography weight body semibold. |
Accessibility
Section titled “Accessibility”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.