Overlays
Sonner
A short message in the corner that confirms something happened, such as a started backup. It disappears after four seconds. Built on svelte-sonner.
import { Toaster, toast } from '@statix/ui/sonner';Playground
<script lang="ts">
import { Toaster, toast } from '@statix/ui/sonner';
</script>
<!-- once, in your root layout -->
<Toaster />
<Button onclick={() => toast.success('Website restored', {
description: 'yoga-berger.de is back to yesterday, 22:05.'
})}>Show toast</Button>Examples
Types
success, info, warning and error add a coloured status icon. The card stays white so the text stays readable.
<script lang="ts">
import { Toaster, toast } from '@statix/ui/sonner';
import { Button } from '@statix/ui/button';
// One Toaster in your root layout is enough. This page renders several, so each gets an id.
const toasterId = 'sonner-types';
</script>
<Toaster id={toasterId} />
<Button variant="outline" onclick={() => toast.success('Website restored', { toasterId })}>
Success
</Button>
<Button variant="outline" onclick={() => toast.info('Backup started', { toasterId })}>Info</Button>
<Button
variant="outline"
onclick={() => toast.warning('yoga-berger.de expires in 14 days', { toasterId })}
>
Warning
</Button>
<Button variant="outline" onclick={() => toast.error('Backup failed', { toasterId })}>Error</Button>
<Button variant="outline" onclick={() => toast('Invoice INV-2026-0412 downloaded', { toasterId })}>
Neutral
</Button>With a description
A second line in ink-2 for the detail: which website, how long it takes.
<script lang="ts">
import { Toaster, toast } from '@statix/ui/sonner';
import { Button } from '@statix/ui/button';
const toasterId = 'sonner-description';
</script>
<Toaster id={toasterId} />
<Button
variant="outline"
onclick={() =>
toast.info('Backup started', {
description: 'yoga-berger.de, takes about two minutes. Your website stays online.',
toasterId
})}
>
Back up now
</Button>
<Button
variant="outline"
onclick={() =>
toast.success('Website restored', {
description: 'yoga-berger.de is back to yesterday, 22:05.',
toasterId
})}
>
Restore website
</Button>With an action
One short action such as Undo. It renders as a small primary pill.
<script lang="ts">
import { Toaster, toast } from '@statix/ui/sonner';
import { Button } from '@statix/ui/button';
const toasterId = 'sonner-action';
function archive() {
toast('Invoice INV-2026-0398 archived', {
description: 'You find it under Invoices, Archive.',
action: {
label: 'Undo',
onClick: () => toast.success('Invoice moved back', { toasterId })
},
toasterId
});
}
</script>
<Toaster id={toasterId} />
<Button variant="outline" onclick={archive}>Archive invoice</Button>Promise
toast.promise shows a spinner while the promise runs and swaps in the success or error message when it settles.
<script lang="ts">
import { Toaster, toast } from '@statix/ui/sonner';
import { Button } from '@statix/ui/button';
const toasterId = 'sonner-promise';
function createBackup() {
const backup = new Promise<{ size: string }>((resolve) =>
setTimeout(() => resolve({ size: '1.2 GB' }), 2000)
);
toast.promise(backup, {
loading: 'Creating backup of yoga-berger.de…',
success: (data) => `Backup created, ${data.size}`,
error: 'Backup failed. Jonas from support will get in touch.',
toasterId
});
}
</script>
<Toaster id={toasterId} />
<Button onclick={createBackup}>Create backup</Button>Guidelines
Do
- Render one <Toaster /> in the root layout and call toast() from anywhere.
- Write the title as a result in a few words: "Backup started", "Website restored".
- Use error toasts for failures the user did not wait for. Show errors in a form next to the field.
Don't
- Don’t put information in a toast that people need later. It disappears.
- Don’t add more than one action.
- Don’t use a toast to ask a question. Use Alert Dialog.
Accessibility
- The toaster is a labelled region ("Notifications alt+T"). Toasts are announced through an aria-live region.
- Alt+T moves focus to the toasts. Timers pause while a toast is hovered or focused.
- Toasts can be swiped away on touch devices. Pass closeButton for a visible close button.
- The status icon is decorative. The title must say the outcome on its own.
API reference
Toaster
renders<section> and accepts its attributesRenders the toasts. Statix sets the card surface, 16px radius, overlay shadow, 15px text and coloured status icons.
| Prop | Type | Default |
|---|---|---|
position | 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' Corner the toasts stack in. | 'bottom-right' |
duration | number Milliseconds before a toast closes. | 4000 |
closeButton | boolean Shows a close button on each toast. | false |
expand | boolean Shows all toasts expanded instead of stacked. | false |
visibleToasts | number How many toasts are visible at once. | 3 |
theme | 'light' | 'dark' | 'system' Statix is light only for now, so the default is light instead of system. | 'light' |
id | string Only needed with several toasters. Target it with toast(…, { toasterId }). | – |
toastOptions | ToastOptions Defaults for every toast. classes are merged with the Statix classes. | – |
| Data attribute | Meaning |
|---|---|
data-sonner-toast | On each toast. |
data-type | "default", "success", "info", "warning", "error" or "loading". |
toast
Re-exported from svelte-sonner. toast(title, options), toast.success, toast.info, toast.warning, toast.error, toast.loading, toast.promise and toast.dismiss(id?).
| Prop | Type | Default |
|---|---|---|
description | string Second line under the title. | – |
action | { label: string; onClick: (event: MouseEvent) => void } One action button. | – |
cancel | { label: string; onClick?: () => void } A secondary button that closes the toast. | – |
duration | number Overrides the toaster duration. | – |
id | string | number Reuse an id to update a toast in place. | – |
toasterId | string Sends the toast to the Toaster with this id. | – |
toastClasses
The Tailwind classes Statix passes to each toast part. They use ! because svelte-sonner ships unlayered CSS.