Skip to content

Toast

Stable Available in release assets

Present transient, server-authored feedback without requiring a client-side message store.

Toast primary example

Show code
<section class="thin-toast-region" aria-label="Notifications" data-live="polite" data-max="3">
  <article class="thin-toast" data-tone="success" data-timeout="5000" data-toast-key="published">
    <svg class="thin-icon" aria-hidden="true">
      <use href="/icons/sprite.svg#circle-check">
      </use>
    </svg>
    <div>
      <strong>Changes published</strong>
      <p>The pricing page is live.</p>
    </div>
    <button type="button" data-toast-dismiss aria-label="Dismiss changes published">
      <svg class="thin-icon" aria-hidden="true">
        <use href="/icons/sprite.svg#x">
        </use>
      </svg>
    </button>
  </article>
</section>

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

Success toast

Routine status with tone icon, message, and dismiss control.

Show code
<article class="thin-toast" data-tone="success" data-timeout="5000">
  <svg class="thin-icon" aria-hidden="true">
    <use href="/icons/sprite.svg#circle-check">
    </use>
  </svg>
  <div>
    <strong>Changes published</strong>
    <p>The pricing page is live.</p>
  </div>
  <button type="button" data-toast-dismiss aria-label="Dismiss">
    <svg class="thin-icon" aria-hidden="true">
      <use href="/icons/sprite.svg#x">
      </use>
    </svg>
  </button>
</article>

Warning toast

Warning tone uses the same structure with a different semantic color role.

Show code
<article class="thin-toast" data-tone="warning">
  <svg class="thin-icon" aria-hidden="true">
    <use href="/icons/sprite.svg#triangle-alert">
    </use>
  </svg>
  <div>
    <strong>Shipping delay</strong>
    <p>Your order may arrive one day later.</p>
  </div>
  <button type="button" data-toast-dismiss aria-label="Dismiss">
    <svg class="thin-icon" aria-hidden="true">
      <use href="/icons/sprite.svg#x">
      </use>
    </svg>
  </button>
</article>

Danger toast

Error toasts stay persistent until the reader dismisses them or follows an action.

Show code
<article class="thin-toast" data-tone="danger" data-persist>
  <svg class="thin-icon" aria-hidden="true">
    <use href="/icons/sprite.svg#triangle-alert">
    </use>
  </svg>
  <div>
    <strong>Payment method expired</strong>
    <p>Update billing details before renewal.</p>
  </div>
</article>

Pending toast

Pending work uses a dashed border treatment while the server completes the task.

Show code
<article class="thin-toast" data-state="pending">
  <svg class="thin-icon" aria-hidden="true">
    <use href="/icons/sprite.svg#loader-circle">
    </use>
  </svg>
  <div>
    <strong>Publishing changes</strong>
    <p>This usually takes a few seconds.</p>
  </div>
</article>

Anatomy

  • Native .thin-toast host
  • Lucide tone icon
  • Semantic heading and message
  • Optional action
  • Optional dismiss control

Variants and sizes

  • Success — shown above
  • Warning — shown above
  • Danger — shown above
  • Pending — shown above
  • Persistent — shown above

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

  • Inserted
  • Paused on hover or focus
  • Persistent
  • Dismissed
  • Duplicate key
  • Overflow
  • Long localized copy
  • Narrow container
  • 200% and 400% zoom

Structured state fixtures are not published for this item yet.

Interaction and keyboard behavior

Server-inserted toasts are observed automatically. Non-actionable status messages may time out; the timer pauses while hovered or focused. A data-toast-dismiss control removes a message without moving focus.

Accessibility

Pair tone with meaningful text and an icon, never color alone. Toasts never steal focus. Place toasts inside a labelled toast region whose live-region mode matches urgency.

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 with data-tone, optional data-timeout, data-persist, data-state="pending", and data-toast-key. Add data-toast-dismiss to a native button.

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, server-rendered messages and actions remain visible in document order; use a form submit or link when dismissal must work without enhancement.

Assets and dependencies

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

Dependencies: None

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

Stability evidence

  • Server-inserted toast observation, dismiss control, timeout, and persistence contracts: 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.

Composes