SwToast
SwToast is a global notification component. Place it once in app.vue or a layout root, then trigger it imperatively via the useToast() composable — no need to import it on every page.
Setup
<!-- app.vue -->
<template>
<NuxtLayout><NuxtPage /></NuxtLayout>
<SwToast />
</template>
SwToast takes no props. It automatically listens to useToast() state and renders all active notifications.
Basic Usage
Call useToast() in any component to get an instance, then use shorthand methods to trigger the appropriate notification type:
const toast = useToast()
toast.success('File saved successfully')
toast.error('Request failed, please try again')
toast.warning('Disk space below 10%')
toast.info('A new version is available')
Four notification types
Click each button to trigger success / error / warning / info notifications.
Custom Title and Duration
Use toast.add() to specify a title, type, and auto-close duration at the same time. Setting duration to 0 prevents the notification from closing automatically — the user must click the close button.
toast.add({
type: 'success',
title: 'Deployment complete',
message: 'The application has been successfully deployed to production.',
duration: 5000, // auto-close after 5 seconds
})
// No auto-close
toast.info('There are pending review tasks', { duration: 0 })
Custom title and duration
Click the button to trigger a notification with a title that auto-closes after 5 seconds.
Queue stacking & manual remove
Card form (title + sticky + X)
Skin token overrides (--sw-toast-*)
useToast() Return Values
| Name | Type | Description |
|---|---|---|
toasts | ToastItem[] | Reactive list of all active notifications |
add | (options: ToastOptions) => void | Add a notification |
remove | (id: string) => void | Manually remove a notification by ID |
success | (message: string, opts?) => void | Shorthand: show a success notification |
error | (message: string, opts?) => void | Shorthand: show an error notification |
warning | (message: string, opts?) => void | Shorthand: show a warning notification |
info | (message: string, opts?) => void | Shorthand: show an info notification |
add() Parameters (ToastOptions)
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
message | string | ✓ | — | Notification body text |
title | string | — | Optional title shown above the body | |
type | 'success' | 'error' | 'warning' | 'info' | 'info' | Notification type, determines icon and color | |
duration | number | 3000 | Auto-close delay in ms; 0 disables auto-close |
Caveats
<SwToast />must be mounted once at the root ofapp.vue, oruseToast()silently does nothing (Rule STO-001) —useToast().success()only pushes onto a global queue; this component is what actually renders it. Without it the queue grows and nothing appears on screen.- ⚠️ Unlike SwModalHost, there is no runtime hint when it's missing — SwModalHost emits a
console.warn; SwToast currently has no such fallback (verified against source), not even a warning. Step one when debugging "toasts don't show" is confirming<SwToast />is inapp.vue. - Pick the feedback channel by scenario — toast isn't universal (Rule UX-008) — use toast for success / lightweight notices; use
useModal()when the user must decide; show field-level validation errors inline (SwFormField). Validation errors stuffed into a toast vanish before the user can read them. - Ships a default skin plus four semantic colors (not zero-styled) — the framework injects
toast.cssby default: a top-centered overlay, a translucent card (background / border / shadow), and per-data-type✓/✕/!/iicons with colors (--sw-toast-icon-success/error/warning/infomap to--success/--destructive/--warning/--info). To recolor, override the corresponding--sw-toast-*variables. The component also emits a[data-type="..."]semantic attribute, which you can select on when you want to restyle the visuals entirely. Turn the whole skin off withframework.styles.toast = falseinswift.config.json.