Toast

Common Toast Variants

Position Variants

Stacking Behavior

When multiple toasts fire in quick succession:

• Stack vertically (newest on top or bottom — be consistent)
• Limit visible toasts (3–5 max). Queue excess and show sequentially.
• Expand on hover — collapse stacked toasts into a compact pile, expand on hover to reveal all.

Toast Properties

Design Token Mappings

Use the Animation Generator to create polished slide + fade entrance effects for your toasts.

Toast Lifecycle States

Auto-Dismiss Duration Guidelines

Progress Indicator

Some toast implementations show a shrinking progress bar at the bottom to indicate remaining time. This is helpful for toasts with actions — users can see how long they have to hit "Undo." Pause the progress bar on hover along with the timer.

Configure entrance/exit animations with our Transition Generator — a cubic-bezier(0.16, 1, 0.3, 1) easing produces a natural slide-in feel.

WCAG Requirements

ARIA Implementation

The toast container should use a live region so screen readers announce new toasts without moving focus:

<!-- Toast container (always in the DOM) -->
<div class="toast-region" role="region" aria-label="Notifications">
  <ol aria-live="polite" aria-relevant="additions">
    <!-- Toasts are injected here -->
    <li role="status">
      <p class="toast-title">Settings saved</p>
    </li>
  </ol>
</div>

Key decisions:

• role="status" — For informational toasts. Screen readers announce them at the next pause (non-intrusive).
• role="alert" — For error/warning toasts that need immediate attention. Screen readers interrupt current speech. Use sparingly.
• aria-live="polite" — On the container. New children are announced without interruption.
• aria-live="assertive" — Only for critical errors. Interrupts the user's current screen reader output.

Keyboard Interaction

Important Accessibility Considerations

1. Don't rely solely on toasts for critical information. Users who are away from the screen, using screen magnifiers, or processing other content may miss them entirely.
2. Keep messages concise. Screen readers announce the entire content — long messages are disorienting when spoken aloud.
3. Toast actions must be reachable by keyboard. The "Undo" button in a toast must be focusable and operable via Tab + Enter.
4. Respect motion preferences. Use prefers-reduced-motion to disable slide animations and use instant opacity transitions instead.

For accessible notification patterns, see our ARIA Attributes Guide and WCAG Practical Guide.

Do's

• ✅ Keep toast messages to one sentence. "Project saved" is better than "Your project has been successfully saved to the server."
• ✅ Use appropriate variants. Green for success, red for errors. Don't use a success toast for neutral info — color carries meaning.
• ✅ Include an "Undo" action for destructive operations. "Email deleted — Undo" gives users a safety net. It's faster than a confirmation dialog and less disruptive.
• ✅ Pause the timer on hover. Users who are reading the message or reaching for the action button shouldn't have it disappear from under their cursor.
• ✅ Respect prefers-reduced-motion. Replace slide animations with opacity-only transitions for users who've opted out of motion.

Don'ts

• ❌ Don't use toasts for form validation errors. Show errors inline next to the relevant Text Input. A toast saying "Invalid email" doesn't tell the user which field is wrong.
• ❌ Don't stack more than 3–5 toasts. If actions generate frequent toasts, debounce or batch them ("3 items deleted" not three separate toasts).
• ❌ Don't use toasts for permanent information. If the user needs to reference the information later, put it on the page.
• ❌ Don't make toasts the only error channel. Always log errors somewhere persistent (console, error boundary, notification center) in addition to showing a toast.
• ❌ Don't auto-dismiss error toasts too quickly. Errors need more reading time than confirmations. Use 8,000ms+ or require manual dismissal.

Content Guidelines

• Title: 2–6 words, past tense for confirmations ("Settings saved", "Email sent"), present tense for ongoing ("Uploading file…").
• Description: Optional. One sentence of context. "Your changes will take effect in 5 minutes."
• Action label: Single verb or short phrase — "Undo", "Retry", "View", "Dismiss".
• Avoid technical jargon: "Network error" is fine. "ECONNREFUSED 503 timeout" is not.

Cross-System Comparison

Notable Approaches

Sonner has emerged as the de facto toast library in the React ecosystem (2024–2026). Created by Emil Kowalski, it handles stacking with an elegant "expand on hover" pattern, supports promise-based toasts (toast.promise(fetch(…))), and includes swipe-to-dismiss for mobile. Shadcn/ui adopted Sonner as its recommended toast solution, replacing the earlier Radix-based approach.

Material 3 Snackbar is intentionally limited: one snackbar at a time, bottom-center positioning, one optional action. This constraint is a design decision — multiple simultaneous snackbars create noise. If you need multiple notifications, Material recommends a separate notification center.

Ant Design separates toasts into two components: message (compact, top-center, for simple confirmations) and notification (richer, top-right, with title + description + icon). This separation is practical — different feedback needs deserve different treatments.

Radix Toast is deliberately low-level. It handles the accessibility layer (live regions, focus management, swipe gestures) but provides no styling, positioning, or stacking logic. It's a primitive — build your own toast system on top of it, or use Sonner which does this for you.

A key trend: Promise-based toasts that show loading → success/error states have become standard. Instead of managing three separate toasts, you call toast.promise(saveData(), { loading: "Saving…", success: "Saved!", error: "Failed" }) and the toast transitions automatically.