Chapter 34: Toast

Core Idea

A succinct, auto-dismissing notification, rendered into a fixed viewport, with built-in pause-on-hover/focus/window-blur, swipe-to-dismiss, and a keyboard hotkey to jump to the notification region.

Key Concepts

• Anatomy: Provider (wraps the app) → Viewport (fixed notification region) + one or more Root (→ Title, Description, Action, Close).
• Root is not for content requiring a response: it auto-closes; use AlertDialog/Dialog instead for anything that needs to hold the user's attention until they act.
• Pause behavior: the auto-close timer pauses automatically on hover, focus, or window blur, and resumes otherwise — no manual timer management needed.
• Swipe-to-dismiss: Provider's swipeDirection/swipeThreshold plus Root's onSwipeStart/Move/End/Cancel and the --radix-toast-swipe-move-x/y CSS variables drive touch-dismiss gestures and their animation.
• Viewport's hotkey (default ["F8"]): lets keyboard users jump focus straight to the notification region — you're responsible for surfacing hotkey discoverability (e.g. in the label).
• Duplicate toasts: Root's default duration (5000ms from Provider, overridable per-Root) and multiple simultaneous toasts are supported natively.

Reference Tables

Part	Notable props
Provider	duration (default 5000), label* (default "Notification"), swipeDirection, swipeThreshold
Root	type ("foreground"/"background" — affects screen-reader announcement priority), duration, open/onOpenChange, onPause/onResume, swipe callbacks

Key Takeaways

1. Never put a required user action's only path inside a Toast — it auto-dismisses; use Action for a convenience shortcut (e.g. "Undo"), not the sole way to complete a flow.
2. type="background" vs the default "foreground" controls assistive-tech announcement urgency — use "foreground" sparingly, for genuinely important messages.
3. An imperative/programmatic API for triggering toasts from anywhere in the app (not just declaratively rendering Root) is documented separately — most real apps wrap this primitive in a small toast-manager hook.

Connects To

• Alert Dialog: the correct primitive when a response is actually required, instead of a Toast.