Skip to content

Toast region

Stable Available in release assets

Receive and announce a bounded stack of server-authored toast messages with polite, assertive, or silent live-region behavior.

Toast region primary example

Show code
<section class="thin-toast-region" aria-label="Notifications" data-live="polite" data-max="3">
</section>

Each authored example uses the production assets and includes copyable markup.

Polite region

Routine status updates use aria-live=polite.

Show code
<section class="thin-toast-region" aria-label="Notifications" data-live="polite" data-max="3">
</section>

Assertive region

Urgent errors may use aria-live=assertive in a dedicated region.

Show code
<section class="thin-toast-region" aria-label="Urgent errors" data-live="assertive" data-max="2">
</section>

Silent region

data-live=off keeps stacked messages visible without announcing every insertion.

Show code
<section class="thin-toast-region" aria-label="Background jobs" data-live="off" data-max="5">
</section>

Anatomy

  • Labelled region
  • Live-region mode
  • Optional maximum stack size
  • Server-authored .thin-toast children

Variants and sizes

  • Polite — shown above
  • Assertive — shown above
  • Off — shown above

Rendered fixtures exercise authored content and constrained layouts with the same production assets.

  • Empty
  • One message
  • Stacked messages
  • Overflow
  • Duplicate key
  • Long localized copy
  • Narrow container
  • 200% and 400% zoom

Structured state fixtures are not published for this item yet.

Interaction and keyboard behavior

The region observes inserted .thin-toast children, enforces data-max overflow, and reconciles duplicate data-toast-key values.

Accessibility

Give the region an accessible label and choose data-live=polite for routine status, assertive only for urgent errors, or off when announcements would be noisy.

Contract
LIVE
Basis
Native labelled region and authored live mode; no toast-specific APG widget
Evidence
  • tests/unit/behaviors/toast.test.ts

API

Use .thin-toast-region with an accessible label, data-live=polite|assertive|off, and optional data-max. Insert ordinary thin-toast children from the server.

Behavior tier: dependency-free

Structured host, property, and example tables are not authored for this item yet. Use the summary above and the primary example.

Fallback

Without JavaScript, authored toast messages remain visible in document order inside the labelled region.

Assets and dependencies

  • /components.css
  • /behaviors.js
  • /icons/sprite.svg

Dependencies: None

Source: packages/ui/src/items/toast/style.ts

Stability evidence

  • Labelled live-region modes, overflow bounds, and duplicate-key reconciliation: test:tests/unit/behaviors/toast.test.ts
  • Complete item-specific API, fallback, and difficult-state documentation: test:tests/unit/library/overlays-feedback-stable.test.ts
  • Cross-theme, density, localized, narrow-container, zoom, and forced-colors fixture: review:site/src/pages/quality/index.astro#quality-review

Composition

Derived from the examples and style specs, not authored.

Used by