Components / Toast

Toast

Imperative toast queue. Mount <Toast /> once per page, then spawn notifications from anywhere via window.YPAIToast.show(...). Respects prefers-reduced-motion.

Section: Components

Examples

Info

usage.astro | astro 
<button onclick="window.YPAIToast.show({
  title: 'Heads-up',
  body: 'Background sync finished — your data is fresh.',
  variant: 'info',
})">
  Show info toast
</button>

Success

usage.astro | astro 
<button onclick="window.YPAIToast.show({
  title: 'Saved',
  body: 'Configuration saved to your account.',
  variant: 'success',
})">
  Show success toast
</button>

Warning

usage.astro | astro 
<button onclick="window.YPAIToast.show({
  title: 'Almost out of credits',
  body: '7% remaining — top up to avoid throttling.',
  variant: 'warn',
})">
  Show warning toast
</button>

Error

usage.astro | astro 
<button onclick="window.YPAIToast.show({
  title: 'Upload failed',
  body: 'Server returned 502 — retry in a moment.',
  variant: 'error',
  duration: 6000,
})">
  Show error toast
</button>

Persistent (duration: 0)

usage.astro | astro 
<button onclick="window.YPAIToast.show({
  title: 'Manual dismiss',
  body: 'This toast stays until you close it.',
  variant: 'info',
  duration: 0,
})">
  Show persistent toast
</button>

Body-only (no title)

usage.astro | astro 
<button onclick="window.YPAIToast.show({
  body: 'Copied to clipboard.',
  variant: 'success',
})">
  Show body-only toast
</button>

Anatomy

Property Behavior
Region Fixed container at viewport corner with `aria-live` set per variant.
Toast Individual notification card — icon + title + body + dismiss.
Icon Variant-tinted glyph (check, alert, info).
Title Optional bold first line — under 40 chars.
Body Main message — under 80 chars; supports basic inline `<em>`/`<strong>`.
Dismiss Close (X) button — always present, even for auto-dismiss.

Accessibility

  • The toast region uses role="region" + aria-label="Notifications" so SR users can jump straight to it.
  • info + success toasts render with role="status" (polite live region — announced when free).
  • warn + error toasts render with role="alert" (assertive — announced immediately).
  • Auto-dismiss is paused when the toast region has keyboard focus or the cursor is over it.
  • Each toast has a real <button aria-label="Dismiss notification">; Tab + Enter / Space dismiss.
  • Animations honour prefers-reduced-motion — toasts fade in/out without sliding when reduced.

Do / Don't

Property Do Don't
Message length Keep `body` under 80 chars; users glance, never read. Use Toast for terms-of-service or anything they need to act on within the toast.
Confirmation flow Use Toast as the post-action receipt ("Saved."). Use Toast for confirmations that need a yes/no — use Dialog.
Variant choice Pick `error` only for genuine failures; `warn` for risk; `info`/`success` for everything else. Spam `error` for every minor validation issue — desensitises users.
Duration Default 4000ms works for success / info; bump to 6000ms for errors. Use `duration: 0` (persist) unless a manual dismiss matters.
Concurrency Let the queue stack naturally — newest at top. Spawn 5+ toasts at once — collapse them into a single summary instead.

Props

Property Notes
(none) Toast takes no props; mount it once anywhere on the page. -

YPAIToast.show() options

Property Type Default
title string -
body string -
variant info | success | warn | error 'info'
duration number (ms; 0 = persist) 4000

Imperative API

Property Behavior
YPAIToast.show(opts) Spawn a toast. Returns the toast id.
YPAIToast.dismiss(id) Dismiss a specific toast by id.
YPAIToast.clear() Dismiss all toasts.

Usage

my-page.astro | astro 
---
import Toast from '@/components/ui/Toast.astro';
---

<button type="button"
  onclick="window.YPAIToast.show({
    title: 'Saved',
    body: 'Your changes are live.',
    variant: 'success',
    duration: 4000,
  })">
  Save
</button>

<!-- Mount once near the bottom of <body>. -->
<Toast />