Toast

Announce brief asynchronous feedback without interrupting the current task.

<hui-toaster>View source View spec

Interactive

Try it

type, duration

Changes saved

Your profile is up to date.

Undo

Dismiss

Markup

State

Events

<hui-toaster id="playground-toaster" aria-label="Toast preview notifications" position="bottom-right">
  <hui-toast id="playground-toast" type="status" duration="0">
    <hui-toast-title>Changes saved</hui-toast-title>
    <hui-toast-description>Your profile is up to date.</hui-toast-description>
    <hui-toast-action>Undo</hui-toast-action>
    <hui-toast-close>Dismiss</hui-toast-close>
  </hui-toast>
</hui-toaster>

data-state: Waiting for enhancement

No component events yet.

Usage

Use a toast for brief, asynchronous feedback that does not require a blocking decision. Use a dialog when the user must respond before continuing and a field error when feedback belongs to a specific control. Do not put essential instructions only in a toast.

Anatomy

Toaster region: hui-toaster
Toast surface: hui-toast
Projected parts: title, description, action, and close
Generated close: accessible close control present on every toast
State hooks: data-state, data-front, and data-behind

Examples

Fixture exampleSource-backed

<section aria-labelledby="toast-heading">
    <h2 id="toast-heading">Toast examples</h2>
    <hui-toaster id="notifications" max-visible="3" hotkey="F8" aria-label="Notifications"></hui-toaster>
  </section>

API reference

Attribute or API	Meaning
`max-visible`	Maximum simultaneously visible toasts on `hui-toaster`; defaults to `3`.
`hotkey`	Optional key that focuses the front toast control.
`aria-label`, `aria-labelledby`	Accessible name for the toaster region.
`position` / `swipe-direction`	Stack placement and allowed swipe direction.
`type`	`status` (polite) or `alert` (assertive) on `hui-toast`.
`duration`	Auto-dismiss delay in milliseconds; `0` disables the timer.
`close-label`	Accessible label for the generated close control.
`toast()`	Imperative helper that queues a toast with title, description, and optional action.
`announce()`	Announces out-of-band text without creating a visible toast.

A toast emits dismissal and action events; the toaster emits queue changes. Escape collapses the visible stack, configured hotkeys focus its front action or close control, and swipe gestures can dismiss a toast. Toasts pause their timers while hovered or focused. SSR emits an empty named region for client-created queues; declarative toast markup retains deterministic IDs.

Out-of-band announcements

announce and its AnnounceOptions and LivePoliteness types are exported from both hydro-ui and hydro-ui/toast. The helper accepts document, politeness (polite or assertive), dedupeMs (default 1000), throttle (default 0), and strategy. The default strategy="live-region" preserves one document-local channel per politeness. Opting into strategy="native" uses document.ariaNotify() when available, mapping polite messages to normal priority and assertive messages to high priority. Missing or throwing native implementations fall back to the live region. Both strategies share deduplication and throttling, and successful native delivery does not also write a live region.

Use this helper only for messages not already represented by a visible toast. Toast content remains its own primary announcement channel. Native delivery is opt-in pending real assistive-technology validation; browser API availability alone is not sufficient evidence.

States and styling

State	Contract and styling guidance
Default	A visible status toast is announced politely and exposes its action/close controls.
Hover	Hover pauses the timer; retain the close control and use surface aliases.
Active	Action and close controls use `--hui-color-interactive-active` for pressed feedback.
Focus	Focused controls keep a visible ring with `--hui-color-focus-ring`; toast surfaces are not tab stops.
Disabled	Toasts have no disabled state; disable an action only when that action cannot run.
Error	`type="alert"` and `--hui-color-danger` communicate urgent or error feedback; do not rely on color alone.

Queued, visible, and leaving states are exposed through data-state. Leaving toasts remain mounted through the tokenized exit transition; reduced-motion and zero-duration paths remove them without requiring animation.

State channel

Attributes are the source of truth. Style derived state with data-state, ARIA attributes, and the --hui-* token aliases.

Accessibility and keyboard support

Use the native or WAI-ARIA interaction described by this component and keep its accessible name, focus indicator, and keyboard behavior intact.

SSR and forms

Server rendering keeps the named toaster region stable; imperative toast creation is client-only. Declarative toast markup retains its accessible state.

Code

<hui-toaster id="notifications" max-visible="3" aria-label="Notifications">
  <hui-toast id="saved-toast" type="status">
    <hui-toast-title>Saved</hui-toast-title>
    <hui-toast-description>Your changes were saved.</hui-toast-description>
    <hui-toast-action>Undo</hui-toast-action>
    <hui-toast-close>Dismiss</hui-toast-close>
  </hui-toast>
</hui-toaster>

<hui-toaster id="playground-toaster" aria-label="Toast preview notifications" position="bottom-right">
  <hui-toast id="playground-toast" type="status" duration="0">
    <hui-toast-title>Changes saved</hui-toast-title>
    <hui-toast-description>Your profile is up to date.</hui-toast-description>
    <hui-toast-action>Undo</hui-toast-action>
    <hui-toast-close>Dismiss</hui-toast-close>
  </hui-toast>
</hui-toaster>