toast-msg
Non-modal notifications with auto-dismiss, variants, action buttons, and configurable positioning.
Overview
The <toast-msg> component is a container for displaying toast notifications. Toasts appear in a fixed position and automatically dismiss after a configurable duration.
Basic toast usage
<!-- Toast container (place once in your HTML) --><toast-msg id="notifications" position="top-end"></toast-msg> <!-- Show toast via JavaScript --><script> const toast = document.getElementById('notifications'); toast.show({ message: 'This is a toast notification!', variant: 'info' });</script>Attributes
| Attribute | Values | Default | Description |
|---|---|---|---|
position | "top-start", "top-center", "top-end", "bottom-start", "bottom-center", "bottom-end" | — | Screen position for the toast stack |
duration | number | — | Default auto-dismiss duration in milliseconds |
max | number | — | Maximum number of visible toasts |
Variants
Toasts support four variants for different types of messages.
Toast variants
<table class="props-table"> <thead> <tr> <th>Variant</th> <th>Use Case</th> </tr> </thead> <tbody> <tr> <td><code>info</code></td> <td>General information, updates, neutral messages</td> </tr> <tr> <td><code>success</code></td> <td>Successful operations, confirmations</td> </tr> <tr> <td><code>warning</code></td> <td>Cautionary messages, potential issues</td> </tr> <tr> <td><code>error</code></td> <td>Errors, failures, critical issues</td> </tr> </tbody> </table> </section> <section> <h2>Positions</h2> <p>Use <code>position</code> to control where toasts appear on the screen.</p> <code-block language="html" show-lines label="Toast position options" data-escape><toast-msg id="toast-top-start" position="top-start"></toast-msg><toast-msg id="toast-top-center" position="top-center"></toast-msg><toast-msg id="toast-top-end" position="top-end"></toast-msg><toast-msg id="toast-bottom-start" position="bottom-start"></toast-msg><toast-msg id="toast-bottom-center" position="bottom-center"></toast-msg><toast-msg id="toast-bottom-end" position="bottom-end"></toast-msg>Action Buttons
Toasts can include an action button for user interaction.
Toast with action button
toast.show({ message: 'File moved to trash.', variant: 'info', action: 'Undo', onAction: () => { // Handle undo action console.log('Undo clicked!'); }});Duration Control
Control how long toasts remain visible before auto-dismissing.
Toast duration options
</section> <section> <h2>Dismissible Control</h2> <p>By default, toasts include a dismiss button. Set <code>dismissible: false</code> to remove it.</p> <code-block language="javascript" show-lines label="Dismissible control" data-escape// With dismiss button (default)toast.show({ message: 'Can be dismissed', dismissible: true }); // Without dismiss buttontoast.show({ message: 'Auto-dismiss only', dismissible: false });JavaScript API
show(options)
Display a toast notification.
| Option | Type | Default | Description |
|---|---|---|---|
message |
string | - | The message to display (required). |
variant |
string | "info" |
Toast variant: info, success, warning, error. |
duration |
number | 5000 |
Auto-dismiss duration in ms. Set to 0 to disable. |
dismissible |
boolean | true |
Whether to show a dismiss button. |
action |
string | - | Optional action button text. |
onAction |
function | - | Callback when action button is clicked. |
Full show() API example
const toast = document.querySelector('toast-msg'); // Full example with all optionsconst toastElement = toast.show({ message: 'Settings saved successfully!', variant: 'success', duration: 5000, dismissible: true, action: 'View', onAction: () => { window.location.href = '/settings'; }}); // Returns the toast DOM elementconsole.log(toastElement);dismissAll()
Dismiss all visible toasts and clear the queue.
Events
The component dispatches events when toasts are shown or hidden.
| Event | Detail | Description |
|---|---|---|
toast-msg:show |
{ toast: HTMLElement } |
Fired when a toast is displayed. |
toast-msg:hide |
{ toast: HTMLElement } |
Fired when a toast is dismissed. |
Toast event listeners
const toastContainer = document.querySelector('toast-msg'); toastContainer.addEventListener('toast-msg:show', (event) => { console.log('Toast shown:', event.detail.toast);}); toastContainer.addEventListener('toast-msg:hide', (event) => { console.log('Toast hidden:', event.detail.toast);});Accessibility
ARIA Attributes
- The toast container has
role="region"andaria-label="Notifications" - The container has
aria-live="polite"so new toasts are announced - Each toast has
role="alert"
Screen Reader Behavior
When a toast appears, screen readers announce its content. The aria-live="polite" setting ensures announcements don't interrupt the user.
Best Practices
- Keep toast messages brief and actionable
- Don't use toasts for critical information that requires action
- Provide sufficient time for users to read the message
- Use appropriate variants to convey message type
- Ensure dismiss buttons are accessible via keyboard
Common Patterns
Form Submission Feedback
Form submission feedback
form.addEventListener('submit', async (e) => { e.preventDefault(); try { await submitForm(new FormData(form)); toast.show({ message: 'Form submitted successfully!', variant: 'success' }); } catch (error) { toast.show({ message: 'Failed to submit form. Please try again.', variant: 'error', duration: 0 // Don't auto-dismiss errors }); }});Async Operation Feedback
Async operation with undo
async function deleteItem(id) { const item = await fetchItem(id); await api.delete(`/items/${id}`); toast.show({ message: `"${item.name}" deleted`, variant: 'info', action: 'Undo', onAction: async () => { await api.restore(`/items/${id}`); toast.show({ message: 'Item restored', variant: 'success' }); } });}Connection Status
Online/offline status notifications
window.addEventListener('offline', () => { toast.show({ message: 'You are offline. Changes will be saved locally.', variant: 'warning', duration: 0 });}); window.addEventListener('online', () => { toast.dismissAll(); toast.show({ message: 'Back online! Syncing changes...', variant: 'success' });});