Skip to content
Kimenpre-v1documentation home
Color scheme

ki-toaster

The one place toasts appear: it paints its ki-toast children in the top layer at a corner of the viewport, stacks them from the top down in arrival order, shows the newest max (3 by default) and queues the older ones, without covering the page beside them.

<ki-toaster placement="bottom-end"></ki-toaster>
<script>
document.querySelector('ki-toaster').show({
tone: 'success',
title: 'Changes saved',
message: 'Workspace settings are up to date.',
});
</script>

placement accepts top-center, top-end, bottom-center and bottom-end (default); end follows the writing direction, and a narrow touch screen always uses the bottom center. The distance from the edges and the gap between toasts are the --ki-toaster-* tokens.

When to use: once per page (or once inside a modal ki-dialog), as the place every ki-toast of the application appears in: append toasts to it, or call show(). Choose the corner with placement.

When not to use: do not put anything but ki-toast elements in it; do not use it for persistent content, which belongs in the page or in ki-alert. Assistive technology note: while it shows toasts the toaster is a group named by label, never a landmark; F6 moves focus into it and Escape on a toast returns focus to where it was. An empty toaster exposes nothing and covers nothing.

Properties & attributes

AttributePropertyTypeDefaultDescription
labellabelstring'Notifications'Accessible name of the group the toaster exposes while it shows toasts. Override for localization. When to use: provide the name in the document language. When NOT to use: do not put a message here.
maxmaxnumber3How many toasts show at once: the newest ones. Older toasts wait, and come back with their full time as shown ones leave. A toast holding focus keeps its place until focus leaves the toaster; the oldest other one waits instead. A value below 1 or not a whole number shows 3. When to use: lower it on small screens or busy applications. When NOT to use: do not raise it to show every toast; a tall stack covers the page.
placementplacement"bottom-center" | "bottom-end" | "top-center" | "top-end" | string & {}'bottom-end'Corner or edge of the viewport the stack sits against; end follows the writing direction. On a coarse pointer and a viewport narrower than 40rem the stack always sits at the bottom center. Unknown values place the stack at the bottom end. When to use: keep toasts away from where the page's own controls live. When NOT to use: do not change it per toast; one toaster keeps one place.

Methods

MethodDescription
show(options: KiToastShowOptions) => Promise<HTMLElement>Raises a toast: creates a ki-toast from tone, title (its heading), message, duration, dismissible and action (a ghost ki-button size="sm" in its action slot that calls onClick), appends it to the toaster and resolves with it. Once the toast has left it is removed from the page. The toaster does not bundle ki-toast or ki-button: define them, as for toasts written in markup. When to use: raise a toast from script without writing its markup. When NOT to use: a toast written in markup stays the page's own: append it instead, and it is never removed.

Slots

SlotDescription
(default)The ki-toast elements, in arrival order. Other children are not counted, queued or placed.

CSS parts

PartDescription
stackThe stack in the top layer: placement, edge distance, gap between toasts and width.

CSS custom properties

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

TokenDescription
--ki-toast-widthdimension used by the toast component for the widest a toast gets (issue #353: 22.5rem).
--ki-toaster-gapdimension used by the toaster component for the gap between stacked toasts (spec 049 FR-014).
--ki-toaster-inset-blockdimension used by the toaster component for the distance between the stack and the top or bottom edge of the viewport (spec 049 FR-014).
--ki-toaster-inset-inlinedimension used by the toaster component for the distance between the stack and the end edge of the viewport (spec 049 FR-014).
--ki-typography-family-bodysemantic font family for typography family body.

While it shows toasts the toaster is a group named by label (Notifications by default), not a landmark: keep it inside one of the page’s landmarks. F6 moves focus into it and Escape on a toast returns focus to where it was; an empty toaster exposes nothing.

Open ki-toaster in Storybook