Developer Docs
Quick reference guides with props tables, usage examples, and best practices for rapid development
Toast
Temporary notification messages
Toast
Lightweight notification system for displaying brief messages to users. Toasts appear at the top of the screen, auto-dismiss after a duration, and support actions. Perfect for success messages, errors, and user feedback.
API Reference
showToast function accepts either simple parameters or a configuration object.
🔌 Simple API
showToast(message, variant?, duration?)| Parameter | Type | Default | Description |
|---|---|---|---|
| message | string | Function | - | Toast message text or reactive function |
| variant | 'info'|'success'|'warning'|'error' | 'info' | Toast type (determines icon and border color) |
| duration | number | 3000 | Auto-hide duration in milliseconds (0 = persistent) |
⚙️ Config Object API
showToast({ message, variant?, duration?, action? })| Prop | Type | Description |
|---|---|---|
| message | string | Function | Toast message text or reactive function |
| variant | string | Object | Variant name or custom variant object { bgClass, iconClass } |
| duration | number | Auto-hide duration in ms (0 = persistent) |
| action | Object | Action button: { text: string, handler: Function } |
💻 Basic Usage
Simple Toasts
// Simple toasts with variant
showToast('Saved successfully!', 'success');
showToast('Something went wrong', 'error');
showToast('Please review your input', 'warning');
showToast('New message received', 'info');
// Default variant (info)
showToast('This is a notification');⏱️ Custom Duration
Control how long toasts stay visible. Set to 0 for persistent toasts (must be manually closed).
// Short duration (1 second)
showToast('Quick notification', 'info', 1000);
// * - Default duration (3 seconds)
showToast('Normal notification', 'success');
// Long duration (10 seconds)
showToast('Important message', 'warning', 10000);
// ** - Persistent (must be manually closed)
showToast('Action required', 'error', 0);🎯 Toasts with Actions
Add action buttons to toasts for quick interactions (e.g., Undo, View, Retry).
// Toast with undo action
showToast({
message: 'Item deleted',
variant: 'error',
duration: 5000,
action: {
text: 'Undo',
handler: () => {
// Restore deleted item
restoreItem();
showToast('Deletion undone', 'success');
}
}
});
// Toast with view action
showToast({
message: 'New message received',
variant: 'info',
action: {
text: 'View',
handler: () => navigateToMessages()
}
});
// Toast with retry action
showToast({
message: 'Upload failed',
variant: 'error',
duration: 0, // Persistent
action: {
text: 'Retry',
handler: () => retryUpload()
}
});🚀 Reactive Messages
Toast messages can be reactive functions that update dynamically.
// Reactive message with counter
const count = van.state(0);
const interval = setInterval(() => count.val++, 1000);
showToast({
message: () => `Processing: ${count.val} items`,
variant: 'info',
duration: 0 // Persistent while processing
});
// When done
clearInterval(interval);
showToast('Processing complete!', 'success');
// Reactive message with state
const status = van.state('Connecting...');
showToast({
message: () => status.val,
variant: 'info',
duration: 0
});
// Update status
status.val = 'Connected';
status.val = 'Syncing data...';⚡️ Best Practices
✓ Do This
✓Keep Messages Brief
- Use concise one-line messages for best readability and quick comprehension
✓Use Appropriate Variants
- Choose the correct variant (success/error/warning/info) to match the message type
✓Success for Completed Actions
- Use success toasts to confirm completed actions like saves, updates, and deletions
✓Error for Failures
- Use error toasts for failures that need user attention or action
✓Provide Undo Actions
- Add action buttons for reversible operations (Undo, Retry, View)
✓Use Persistent for Critical Errors
- Set duration: 0 for critical errors that require user acknowledgment
✓Test on Mobile
- Verify toasts appear correctly on mobile devices (auto-centered and responsive)
✗ Avoid This
✗Don't Use for Complex Information
- Avoid using toasts for complex messages; use Modal component instead
✗Don't Stack Many Toasts
- Avoid showing multiple toasts simultaneously; combine or sequence them
✗Don't Use Long Durations for Minor Notifications
- Keep minor notifications brief (1-3 seconds) to avoid cluttering the UI
✗Don't Forget Action Buttons
- Provide action buttons for important toasts that users may need to act on
✗Don't Misuse Variants
- Never use info variant for errors or success variant for warnings
✗Don't Show Toast on Every Action
- Avoid showing toasts for every minor action; reserve for significant events
✗Don't Use Extremely Short Durations
- Avoid durations less than 1 second; users need time to read the message
✨ Key Features
⭑Auto-Dismiss with Configurable Duration
- Toasts automatically hide after specified duration (default 3 seconds)
⭑Manual Close Button
- Always includes a close button for manual dismissal
⭑Keyboard Accessible
- Auto-focuses close button for keyboard navigation and screen reader support
⭑Smooth Animations
- Polished slide-in and slide-out transitions for professional feel
⭑Automatic Stacking
- Multiple toasts stack vertically with proper spacing
⭑Singleton Container
- Efficient DOM usage with single container for all toasts
⭑Action Button Support
- Add interactive buttons for Undo, View, Retry, and other quick actions
⭑Reactive Messages
- Messages can be reactive functions that update dynamically
⭑Semantic Variants
- Built-in variants: success, error, warning, and info with appropriate styling
⭑Custom Variant Support
- Create custom variants with bgClass and iconClass properties
⭑Persistent Toasts
- Set duration: 0 for toasts that require manual dismissal
⭑Auto-Cleanup
- Automatically removes hidden toasts from DOM for clean memory management
💡 Common Use Cases
✅Success Confirmation
Confirm successful actions (save, delete, update).
// After save
showToast('Changes saved successfully', 'success');
// After delete with undo
showToast({
message: 'Item deleted',
variant: 'success',
action: { text: 'Undo', handler: restore }
});❌Error Notification
Alert users to failures or validation errors.
// API error
showToast('Failed to save changes', 'error', 5000);
// Validation error with retry
showToast({
message: 'Network error',
variant: 'error',
duration: 0, // Persistent
action: { text: 'Retry', handler: retryRequest }
});⚠️Warnings
Warn about important conditions or limitations.
showToast('Unsaved changes will be lost', 'warning', 5000);
showToast('Storage limit almost reached', 'warning');ℹ️Information
Provide non-critical updates or status.
showToast('New messages available', 'info');
showToast('Syncing in background', 'info');Explore More Components
Browse other component categories