Non-modal notifications with auto-dismiss, variants, action buttons, and configurable positioning.
Overview
The <toast-wc> component is a container for displaying toast notifications. Toasts appear in a fixed position and automatically dismiss after a configurable duration.
<!-- Toast container (place once in your HTML) -->
<toast-wc id="notifications" data-position="top-end"></toast-wc>
<!-- Show toast via JavaScript -->
<script>
const toast = document.getElementById('notifications');
toast.show({
message: 'This is a toast notification!',
variant: 'info'
});
</script>
Attributes
| Attribute |
Type |
Default |
Description |
data-position |
string |
"top-end" |
Position: top-start, top-center, top-end, bottom-start, bottom-center, bottom-end |
data-duration |
number |
5000 |
Default auto-dismiss duration in milliseconds. Set to 0 for no auto-dismiss. |
data-max |
number |
5 |
Maximum number of visible toasts. Additional toasts are queued. |
Variants
Toasts support four variants for different types of messages.
// Info variant (default)
toast.show({ message: 'Informational message', variant: 'info' });
// Success variant
toast.show({ message: 'Operation successful!', variant: 'success' });
// Warning variant
toast.show({ message: 'Please review', variant: 'warning' });
// Error variant
toast.show({ message: 'Something went wrong', variant: 'error' });
| Variant |
Use Case |
info |
General information, updates, neutral messages |
success |
Successful operations, confirmations |
warning |
Cautionary messages, potential issues |
error |
Errors, failures, critical issues |
Positions
Use data-position to control where toasts appear on the screen.
<toast-wc id="toast-top-start" data-position="top-start"></toast-wc>
<toast-wc id="toast-top-center" data-position="top-center"></toast-wc>
<toast-wc id="toast-top-end" data-position="top-end"></toast-wc>
<toast-wc id="toast-bottom-start" data-position="bottom-start"></toast-wc>
<toast-wc id="toast-bottom-center" data-position="bottom-center"></toast-wc>
<toast-wc id="toast-bottom-end" data-position="bottom-end"></toast-wc>
Action Buttons
Toasts can include an action button for user interaction.
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.
// Quick notification (2 seconds)
toast.show({ message: 'Quick!', duration: 2000 });
// Default duration (5 seconds)
toast.show({ message: 'Normal timing' });
// Long duration (10 seconds)
toast.show({ message: 'Stays longer', duration: 10000 });
// No auto-dismiss (0)
toast.show({ message: 'Manual dismiss only', duration: 0 });
Dismissible Control
By default, toasts include a dismiss button. Set dismissible: false to remove it.
// With dismiss button (default)
toast.show({ message: 'Can be dismissed', dismissible: true });
// Without dismiss button
toast.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. |
const toast = document.querySelector('toast-wc');
// Full example with all options
const toastElement = toast.show({
message: 'Settings saved successfully!',
variant: 'success',
duration: 5000,
dismissible: true,
action: 'View',
onAction: () => {
window.location.href = '/settings';
}
});
// Returns the toast DOM element
console.log(toastElement);
dismissAll()
Dismiss all visible toasts and clear the queue.
// Dismiss all toasts
toast.dismissAll();
Events
The component dispatches events when toasts are shown or hidden.
| Event |
Detail |
Description |
toast-show |
{ toast: HTMLElement } |
Fired when a toast is displayed. |
toast-hide |
{ toast: HTMLElement } |
Fired when a toast is dismissed. |
const toastContainer = document.querySelector('toast-wc');
toastContainer.addEventListener('toast-show', (event) => {
console.log('Toast shown:', event.detail.toast);
});
toastContainer.addEventListener('toast-hide', (event) => {
console.log('Toast hidden:', event.detail.toast);
});
Accessibility
ARIA Attributes
- The toast container has
role="region" and aria-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.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 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
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'
});
});