Toast — wd-toast

Category: Overlay · Tag: wd-toastBack to: Components overview

---

What it does

Notification toasts: small colored messages that slide into a screen corner, stack, and dismiss themselves. Nothing renders until your own code triggers one — use it for "saved", "failed", "heads up" feedback after an action on the page.

Unlike most components, the toast takes no slotted content — everything it shows comes from the method call that triggers it.

---

Adding it & its settings

Add Component → Overlay → Toast. Add it once per page (or in a layout to share it across pages) and give it an #id — your code targets it by that id.

Basic Settings (all components): #id, Classes, Inline Style.

Component Settings:

Setting	What it does
Success / Warning / Danger / Info color	The background color for each toast kind — any CSS color string (#16a34a, rgba(22,163,74,0.95), teal). Leave empty for the built-in defaults (green / amber / red / blue).
Display duration (ms)	How long each toast stays visible — default 5000. 0 makes toasts sticky: they stay until the visitor closes them.
Display close button	Shows an ✕ on every toast. A sticky toast (duration: 0) gets one regardless — it must be closable somehow.
Horizontal / Vertical position	Where the stack lives: left / center / right × top / bottom. Default bottom-right.

---

Triggering it

Call one of the four kind methods with a payload — typically from a button's onclick event or a page script:

document.querySelector('#my-toast').toggleSuccess({ title: 'Saved', description: 'All changes stored.' })
document.querySelector('#my-toast').toggleWarn({ title: 'Careful', description: 'Storage almost full.' })
document.querySelector('#my-toast').toggleInfo({ description: 'A new version is available.' })
document.querySelector('#my-toast').toggleError({ title: 'Failed', duration: 0 })   // sticky

• The method picks the color: toggleSuccess → success color, toggleWarn → warning, toggleInfo → info, toggleError → danger.
• The payload takes title and/or description (at least one — an empty call is ignored) and an optional duration that overrides the setting for that one toast (0 = sticky).
• clearToasts() dismisses everything — the visible stack and the waiting queue.
• Each dismissal emits a toastDismissed event (detail: { id, kind }).

How the queue behaves

• Up to 4 toasts show at once, stacked at the configured position (newest nearest the screen edge). Further calls wait in line and slide in as slots free — a burst of ten calls never floods the screen.
• Hovering a toast pauses its countdown (and its progress bar); moving away resumes it.
• Each timed toast shows a thin progress strip draining toward dismissal.

---

Styling

The four kind colors come from the settings (above) — CSS variables handle shape and typography:

Layout & shape

Variable	Default
--wd-toast-opacity	1
--wd-toast-border-radius	0.5rem
--wd-toast-padding	0.75rem 1rem
--wd-toast-width	auto
--wd-toast-min-width	280px
--wd-toast-max-width	380px
--wd-toast-gap	0.75rem (space between stacked toasts)
--wd-toast-offset	1rem (distance from the screen edges)
--wd-toast-box-shadow	0 4px 12px rgba(0,0,0,0.15)
--wd-toast-z-index	9999
--wd-toast-text-color	#fff

Title

Variable	Default
--wd-toast-title-font-family	inherit
--wd-toast-title-font-size	1rem
--wd-toast-title-font-weight	600
--wd-toast-title-font-align	start

Description

Variable	Default
--wd-toast-description-font-family	inherit
--wd-toast-description-font-size	0.875rem
--wd-toast-description-font-weight	normal
--wd-toast-description-font-align	start

Icon & progress

Variable	Default
--wd-toast-icon-display	block — set none to hide the type icons
--wd-toast-icon-size	1.25rem
--wd-toast-progress-height	3px — set 0 to hide the progress strip
--wd-toast-progress-color	rgba(255,255,255,0.45)

/* example: softer, wider toasts without icons */
wd-toast {
  --wd-toast-border-radius: 1rem;
  --wd-toast-max-width: 440px;
  --wd-toast-icon-display: none;
  --wd-toast-opacity: 0.95;
}

::part()

Part	Element
toast-<id>	The fixed stack container.

---

Snackbar preset

A snackbar is not a separate component — it's a wd-toast configured to look like one: a single, quiet, bottom-centered strip. Add a second toaster with these settings (a page can hold several toasters, each with its own #id):

Component Settings: Horizontal position Center · Vertical position Bottom · Display duration ~3000 · Display close button off (calls can still pass duration: 0 when one must be dismissed by hand — the close button appears automatically for those).

Inline Style (or CSS):

--wd-toast-icon-display: none;        /* no type icons — snackbars are plain */
--wd-toast-progress-height: 0;        /* no progress strip */
--wd-toast-border-radius: 0.25rem;
--wd-toast-min-width: 344px;

Trigger it with a description only — a snackbar is a one-liner:

document.querySelector('#my-snackbar').toggleInfo({ description: 'Link copied to clipboard.' })
document.querySelector('#my-snackbar').toggleError({ description: 'Connection lost — retrying…' })

Everything else carries over for free: the 4-visible cap and FIFO queue, hover-pause, and the kind colors (use the color settings to mute them — e.g. a dark neutral #323232 for all four kinds gives the classic Material snackbar look).

---

Notes

• One toaster per page is the pattern — putting it in a layout gives every page under that layout the same toaster.
• Kind ↔ setting mapping: toggleWarn uses the Warning color, toggleError uses the Danger color.
• The stack container ignores clicks (pointer-events: none) except on the toasts themselves — it never blocks the page under it.
• Announced politely to screen readers (aria-live="polite", role="status").