Toaster
import "@taprootio/espalier/toaster";
<esp-toaster>
A toast notification container that listens for "show-toast"
events on EspBus and renders them as stacked esp-info
components. Place one <esp-toaster> in your page layout
(it is included automatically inside <esp-page>).
If more than one toaster is connected — for example a page that
nests several <esp-page>s, each of which injects its own — all
toasts live in one shared stack rendered by a single toaster, so
each showToast() renders once, not once per toaster. The renderer
is re-chosen whenever a toast arrives, a toaster connects or
disconnects, or a toaster's size collapses or expands, preferring a
visible instance, and the whole live stack migrates with it —
a hidden toaster never swallows toasts, and the stack never
fragments across instances. This needs no configuration.
The migration timing contract: routing always skips instances
hidden by display, visibility, opacity: 0, or
content-visibility at decision time, and a live stack re-routes
immediately when its renderer is collapsed via display (the
collapse resizes the toaster, which is observed). A pure
visibility or opacity flip produces no resize, so an
already-rendered stack under one re-routes on the next toast,
connect/disconnect, or resize instead. (The related esp-flyout
uses an explicit standalone opt-out rather than routing, because
its instances are distinct surfaces you target individually.)
Toasts auto-dismiss after their duration (default 5 seconds).
A duration of 0 creates a persistent toast that the user must
dismiss manually.
import { showToast } from "@taprootio/espalier";
showToast({ message: "Saved!", intent: "success" });
showToast({ message: "Connection lost", intent: "danger", duration: 0 });
Try it out — type a message and click a button to fire a toast:
Attributes
<esp-toaster> has the following attributes:
intent
intent has a default value of undefined.
The element's intent — its meaning: neutral
(no pin), or success, warning, danger, info — each pinned
to its fixed status family (blue for info), retunable per theme
via intents. On token-emitting controls a non-neutral intent pins the
filled-action pair to that family, derived over the governing
zone's theme; class-styled chrome (badges, callouts, status pills)
opts out of inline emission and renders its treatment from CSS
classes instead. An intent never repaints the surrounding zone,
which is what contexts are for. Removing the attribute restores
the element's own default intent.
context
context has a default value of undefined.
A theme-defined color zone. The selected context rebinds designer-facing roles and emits a complete, contrast-enforced semantic token table on this host for descendants to inherit.
Methods
<esp-toaster> has the following methods:
traverseToClosest
Traverse up the DOM tree to find the closest element that matches the selector. This method is aware of shadow DOM boundaries and will traverse through them to find the element.
CSS Properties
<esp-toaster> has the following CSS properties:
--esp-toaster-z-index
Stack order of the toaster container. Defaults to 5000.
--esp-toaster-gap
Gap between stacked toasts. Defaults to var(--esp-size-tiny-to-small).
--esp-toaster-padding
Padding around the toaster container. Defaults to var(--esp-size-padding).
--esp-field-background
Background color of the shared field shell. Defaults to var(--esp-color-layer-2).
--esp-field-border-color
Border color of the shared field shell. Defaults to var(--esp-color-border).
--esp-field-border-width
Border width of the shared field shell. Defaults to 1px.
--esp-field-text-color
Text color used inside the shared field shell. Defaults to var(--esp-color-text).
--esp-field-hover-bg
Hover background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-bg
Focus background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-shadow
Shadow color used for shared field focus treatment. Defaults to var(--esp-color-shadow).