Toaster
View in Storybook
Explore interactive examples and all component variations in our Storybook.
The Toaster component provides elegant toast notifications for your application. Built on Sonner, it offers multiple notification types, automatic theming, and smooth animations. Perfect for success messages, error alerts, warnings, and general information display.
Setup
First, add the Toaster component to your app root:
Add the Toaster component to your app root to enable toast notifications.
Basic Toast Types
Toast with Actions
Custom Duration and Position
Rich Content Toasts
Promise-based Toasts
Toast Management
Form Integration
Properties
Toaster
| Property | Type | Description |
|---|---|---|
position | "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right" | Position of the toast container. |
hotkey | string[] | Keyboard shortcut to focus toaster. |
richColors | boolean | Whether to use rich colors for different toast types. |
expand | boolean | Whether toasts should expand on hover. |
duration | number | Default duration for all toasts in milliseconds. |
gap | number | Gap between toasts in pixels. |
visibleToasts | number | Maximum number of visible toasts. |
closeButton | boolean | Whether to show close button on toasts. |
toastOptions | object | Default options for all toasts. |
className | string | Additional CSS classes for the toaster. |
toast Functions
| Function | Parameters | Description |
|---|---|---|
toast.success | (message, options?) | Show a success toast. |
toast.error | (message, options?) | Show an error toast. |
toast.warning | (message, options?) | Show a warning toast. |
toast.info | (message, options?) | Show an info toast. |
toast.promise | (promise, options) | Show toast based on promise state. |
toast.dismiss | (toastId?) | Dismiss specific toast or all toasts. |
toast.loading | (message, options?) | Show a loading toast. |
Toast Options
| Property | Type | Description |
|---|---|---|
duration | number | Duration in milliseconds. Use Infinity for persistent. |
action | { label: string, onClick: () => void } | Action button for the toast. |
cancel | { label: string, onClick: () => void } | Cancel button for the toast. |
id | string | Custom ID for the toast. |
onDismiss | () => void | Callback when toast is dismissed. |
onAutoClose | () => void | Callback when toast auto-closes. |
Accessibility
The Toaster component includes comprehensive accessibility features:
- Screen Reader Support - Toast messages announced to screen readers
- Keyboard Navigation - Keyboard shortcuts and focus management
- ARIA Live Regions - Proper ARIA live regions for dynamic content
- Focus Management - Maintains focus context when toasts appear
- High Contrast - Supports high contrast mode and themes
- Reduced Motion - Respects user's motion preferences
Common Use Cases
The Toaster component is perfect for:
- Form Feedback - Success and error messages for form submissions
- Action Confirmations - Confirm user actions like save, delete, update
- System Notifications - System status updates and alerts
- Progress Updates - Show progress of long-running operations
- Undo Actions - Provide undo functionality for destructive actions
- API Responses - Display API success and error responses
- Real-time Updates - Show real-time notifications and updates
Best Practices
- Appropriate Types - Use correct toast types for different message contexts
- Clear Messages - Write concise and actionable toast messages
- Reasonable Duration - Set appropriate durations based on message importance
- Action Buttons - Provide relevant actions when applicable
- Avoid Overuse - Don't overwhelm users with too many toasts
- Consistent Positioning - Use consistent toast positioning throughout your app
- Error Handling - Always provide clear error messages and recovery options
- Performance - Limit the number of simultaneous toasts for better UX