Toast

Imperative global toasts supporting success/error/warning/info/loading states, action buttons, promise chains, queue governance, and keyboard/screen-reader accessibility; auto-dismisses after 3 seconds by default.

Basic usage

Five types

SuccessErrorWarningInfoLoading

Example

Custom duration

Custom duration

2s5sNo auto-close (0)Close manually

Example

Action buttons

Action buttons (multiple + noDismiss + variants)

Single actionMultiple + noDismissNot closable

Example

Position

Position (9 directions)

top-righttop-lefttop-centerleftcenterrightbottom-centerbottom-leftbottom-right

Example

Promise chain

Promise chain

Simulate successSimulate failure

Example

Lifecycle and onClose

Lifecycle and onClose callback

onClose (auto)onClose (manual)Trigger close

Example

Update and dismiss by id

Update and dismiss by id

Start uploadUpdate progressCompleteClose

Example

Notification storm governance

Max queue and content grouping

Click repeatedly (max=3 queue)Close #N (fill in)Same content (grouped count)Clear all

Beyond 3 visible toasts, extras queue and fill in after one closes; `priority` lets a high-priority toast preempt a visible slot.

Example

Reading grace

Hover/focus pause + remaining-time progress

Pause timer + progressProgress ringTop progress

Window blur (switching tabs/windows) also pauses; disable individually with `pauseOnHover`/`pauseOnFocus`/`pauseOnWindowBlur`.

Example

Keyboard and screen reader

Esc close and screen-reader politeness

Esc closepolite liveassertive live

Example

Swipe to dismiss

Swipe to dismiss

Both directionsLeft only

Example

Collapsed stacking

Collapsed stacking (+N fold / peek)

Trigger repeatedly (fold)

The newest toast stays fully visible while the rest peek behind with a +N badge; hover/focus expands them, clicking +N keeps them expanded.

Example

Variants and animation

Variants (plain/translucent) and animation config

solidplaintranslucentSpringy slow animationRestore default animation

Animation duration/easing go through CSS variables `--oas-toast-enter-duration` / `--oas-toast-leave-duration` / `--oas-toast-ease`, no JS config needed.

Example

Global default config

Global default config (toast.config)

Apply global defaultsRestore defaults

Example

Mount point and named instances

Mount point and named toaster instances

Custom containerconsole instanceClear console instance

Example

Declarative usage

Declarative usage (controlled open)

Toggle visibility (open)

Example

API

Methods

Method	Description
toast.info(options)	Info toast, returns { close, update }
toast.success(options)	Success toast, returns { close, update }
toast.warning(options)	Warning toast, returns { close, update }
toast.error(options)	Error toast, returns { close, update }
toast.loading(options)	Loading toast (not closable), returns { close, update }
toast.promise(promise, opts)	Promise chain: loading → success/error
toast.update(id, options)	Update a toast in place by id; creates one if missing
toast.dismiss(id)	Close a toast by id (visible or queued)
toast.config(options)	Global default config (per-call wins)
toast.toaster(name)	Named instance: isolated stacks/queues/config
destroyAllToast()	Clear all instances

options

Field	Description	Type	Default
title	Title (string or Node)	string | Node	—
description	Description	string	—
action / actions	Action buttons (multiple + noDismiss + variant)	ToastAction | ToastAction[]	—
duration	Auto-dismiss duration (ms); 0 keeps it open	number	3000
closable	Whether it can be closed manually (loading is always unclosable)	boolean	true
position	Position (9 directions)	ToastPosition	top-right
id	Unique id for update / dismiss	string	—
onClose	Close callback (auto/manual/button/dismiss/destroyAll each fire once)	() => void	—
priority	Priority: with the max queue, higher preempts a visible slot	number	0
max	Max visible toasts in the position stack; extras queue	number	Infinity
politeness	Screen-reader sensitivity: assertive / polite	string	by type
showProgress	Remaining-time progress bar (shown when duration>0)	boolean	false
progressRing	Progress ring close button (shown when duration>0)	boolean	false
grouping	Same-content dedupe: merge in the same stack and bump the count badge	boolean	false
swipeDirection	Swipe direction: both/right/left/up/down	string	both
stacked	Collapsed stacking mode (+N fold / peek)	boolean	false
variant	Variant: solid/plain/translucent	string	solid
container	Mount point (element or function), overrides the default host	HTMLElement | () => HTMLElement	—
pauseOnHover / pauseOnFocus / pauseOnWindowBlur	Pause timer toggles (all on by default)	boolean	true

oas-toast

Attributes

Attribute	Description	Type	Default
closable	Whether to show the close button (always disabled while loading)	boolean	—
count	Same-content dedup count badge: with imperative grouping on, repeated dispatches of the same signature increment the count (×N next to the title, shown above 1) and reset the timer	string	0
description	Description text	string	—
duration	Auto-close duration in ms; pass 0 to keep it open	string	3000
id	Instance identity: imperative show/update/dismiss hit the existing instance by id to update/close in place instead of creating a new one; also used as the DOM id	—	—
open	Controlled switch (declarative usage): open="false" hides the whole card and pauses the auto-close timer; absent/other values mean open	string	true
pause-on-focus	Pause the auto-close timer while focus is inside (default on; "false" disables)	—	—
pause-on-hover	Pause the auto-close timer while hovered (default on; "false" disables)	—	—
pause-on-window-blur	Pause the auto-close timer when the window loses focus or the page is hidden (default on; "false" disables)	—	—
politeness	Screen-reader politeness: polite (role=status) / assertive (role=alert, interrupts immediately); an explicit value wins, otherwise derived from type (error is assertive, others polite)	string	—
progress-position	Progress bar position: bottom (default) / top, together with show-progress	string	bottom
progress-ring	Progress-ring close button: an SVG ring around the ✕ tracks the remaining time (completes as duration elapses, when > 0)	boolean	—
show-progress	Show the remaining-time progress bar for auto-close (duration follows duration, frozen while paused)	boolean	—
swipe-direction	Swipe-to-dismiss direction: both (default) / right / left / up / down; the orthogonal axis follows with 0.2 damping	string	both
title	Title text (rendered into the visible title region; absorbed from the host on read so no native hover tooltip remains; pass an empty string to clear); use the "title" slot for rich content	string	—
type	Toast type: info/success/warning/error/loading	string	info
variant	Visual variant: default card / plain (no border/background, text straight out) / translucent (translucent frosted glass)	—	—

Events

Event	Description
oas-close	Emitted on close, detail: { trigger } (trigger: auto/manual/action/close-button/esc/swipe/preempt/external); the node is removed after the leave animation
oas-destroy	Emitted after the node is removed from the DOM (also as a fallback for external removal), detail: { trigger }; used to settle the promise chain
oas-open	Emitted when shown, detail: { trigger }

Slots

Name	Description
title	Rich title content slot; overrides the title attribute text when present

CSS Variables

CSS Variable	Description	Default
--oas-glass-blur	—	none
--oas-glass-refraction	Liquid-glass edge refraction filter (active under data-glass, default none); for local opt-out override with an empty value (--oas-glass-refraction: ;)—not none (mixing none with button-state brightness() invalidates the whole filter declaration)	none
--oas-glass-ring	—	transparent
--oas-toast-ease	—	ease
--oas-toast-enter-duration	—	0.2s
--oas-toast-leave-duration	—	0.2s

• error defaults to role="alert" + aria-live="assertive"; others use role="status" + aria-live="polite"; override with politeness.
• Multiple toasts share one stack container and stack by position; duration timers are cleaned up on close/unmount with no leaks.
• Animation duration/easing are configured via CSS variables --oas-toast-enter-duration / --oas-toast-leave-duration / --oas-toast-ease.