Toast
Last Updated: September 2026Toasts are short system communications that alert the user to the status or an actions.
Source CodeAnatomy
link- 1Icon
- 2Content
- 3Close
Variants
linkInfo
Neutral status. toast.add requires intent, icon, and content.
Success
Confirm a completed action.
Warning
Non-blocking caution after an action.
Danger
Failed action or error feedback.
Promise
toast.promise maps loading / success / error messages automatically.
Usage Guidelines
linkWhen to use
- •For ephemeral feedback after a user action (saved, queued, failed).
- •When the message should not block the page.
- •For async promise progress with loading → success/error.
When not to use
- •For persistent page-level status — use Banner or AlertNotification.
- •When the user must act before continuing — use Modal.
- •For unread counts — use AlertBadge.
Keep toast copy short and outcome-focused.
Don't put long instructions in a toast — use Banner or AlertNotification.
Wrap the tree once with ToastProvider; call useToast only inside it.
Don't use toasts for persistent page status — prefer Banner or AlertNotification. Always call useToast only under ToastProvider.
Behaviors
linkProvider + hook
- •ToastProvider owns the portal viewport (bottom-right) and toast list.
- •useToast() returns { add, update, close, promise } and must run under ToastProvider.
add options
- •add requires intent, icon, and content (mapped to description internally).
- •Optional id lets you update or close a specific toast.
promise helper
- •promise shows loading (info/loading icon), then success or danger based on settle.
- •success and error accept a string or a callback receiving the result/error.
Content Guidelines
linkCopy
- •Prefer under ~60 characters.
- •Describe the outcome ('Note saved'), not the control ('Click save').
- •Synthetic healthcare-safe copy only.
Accessibility
linkText & Labels
- •content is announced as the toast description.
- •Each toast includes a close control via IconButton.
ARIA attributes
- •Toasts live in a dedicated viewport; avoid stacking critical instructions only in toasts.
Keyboard Support
- •Users can dismiss with the close control; focus returns to the page.
WCAG Compliance Standards
FAQs
linkWhy isn't Toast exported for direct rendering?
Render ToastProvider once and drive UI through useToast(). Toast instances are managed internally.
What does add require?
intent, icon, and content. Optional id for later update/close.
How do live examples stay valid?
Define a child component that calls useToast, then wrap it with ToastProvider in the same example.