Feedback & Status
Toaster
Brief messages that confirm what just happened — a payment recorded, a notice sent — without taking the user away from what they are doing. Place one toaster near the root of the page and call toast() on it; messages stack in the top-right corner as raised cards, above everything else on the page.
Messages leave on their own after duration, and the clock stops while the
pointer is over the stack or focus is inside it, so a message is never pulled
away while someone is reading it or reaching for its close button. Only the
newest max messages are kept.
Preview
Section titled “Preview”<nana-button
variant="secondary"
onclick="
document
.getElementById('toaster-preview')
.toast({
variant: 'success',
title: 'Payment recorded',
message: 'KES 42,000 from Kamau Juma for Unit 4B.',
})
"
>
Record payment
</nana-button>
<nana-button
variant="secondary"
onclick="
document
.getElementById('toaster-preview')
.toast({
variant: 'danger',
title: 'M-Pesa sync failed',
message: 'Retrying in one minute.',
duration: 0,
})
"
>
Fail a sync
</nana-button>
<nana-toaster id="toaster-preview"></nana-toaster> <script lang="ts">
import { NanaToaster, toast } from '$lib/components/ui/toaster';
import { NanaButton } from '$lib/components/ui/button';
</script>
<div class="flex flex-wrap gap-2">
<NanaButton
onclick={() =>
toast({
title: 'Payment recorded',
description: 'KES 45,000 from Unit 4B.',
variant: 'success',
})}
>
Success
</NanaButton>
<NanaButton
variant="outline"
onclick={() => toast({ title: 'Lease ends in 30 days', variant: 'warning' })}
>
Warning
</NanaButton>
<NanaButton
variant="outline"
onclick={() =>
toast({
title: 'Sync failed',
description: 'Check the connection and try again.',
variant: 'danger',
duration: 0,
})}
>
Error
</NanaButton>
</div>
<NanaToaster /> Installation
Section titled “Installation”npm install @nana-tec/ui-componentsOr copy the source in and own it:
npx @nana-tec/ui add toaster --framework web-componentsnpx @nana-tec/ui add toaster --framework svelteLands in src/lib/components/ui/toaster/ as NanaToaster.svelte, styled with Tailwind
classes that resolve to the design tokens. Requires Tailwind v4.
Import
Section titled “Import”
Import the autoloader once, in your app's entry point. Every <nana-*> tag then works anywhere, and
each component downloads only the first time a page uses it:
import "@nana-tec/ui-components/autoloader";import "@nana-tec/ui-components/theme";The second line gives every component the Nana look and the design tokens behind it. Leave it out to style the components entirely yourself.
Import a component directly when it must be ready at once: on screen at first paint, or when you call its methods straight away. The two mix freely:
import "@nana-tec/ui-components/toaster";
Copied in with npx @nana-tec/ui add toaster? Import your project's own
@/lib/nana-ui/autoloader.js once instead; the CLI keeps it up to date.
The example below calls the toaster’s methods straight away, so it imports the toaster directly.
<script lang="ts"> import { NanaToaster, toast } from '$lib/components/ui/toaster';</script>
<NanaToaster placement="bottom-right" />
<button onclick={() => toast({ title: 'Saved', variant: 'success' })}>Save</button>Put one Toaster in the layout and call toast() from anywhere. Toasts leave
after duration milliseconds (0 keeps them) and wait while the pointer or focus is on
them. The toaster sits in the top layer, so it stays above an open dialog.
Put one toaster near the root of the page and send messages to it from anywhere:
import "@nana-tec/ui-components/toaster";
const toaster = document.querySelector("nana-toaster");
toaster.toast({ variant: "success", title: "Payment recorded", message: "KES 42,000 from Kamau Juma for Unit 4B.",});toast() returns the message’s id. Pass your own id to replace a message in
place — “Syncing…” becoming “Synced” — instead of stacking a second one, and
call dismiss(id) to take it down early.
| Field | Default | Description |
|---|---|---|
message | — | The text of the message |
title | — | A bold heading above it |
variant | info | info, success, warning, danger or neutral, as on alert |
duration | the toaster’s | How long it stays, in ms; 0 keeps it until dismissed |
dismissible | true | Whether it has a close button |
id | generated | Reuse one to replace a message |
Variants
Section titled “Variants”The variant colours the icon and the countdown bar; the card itself stays on the page surface.
<nana-button
size="sm"
variant="secondary"
onclick="
document
.getElementById('toaster-variants')
.toast({
variant: 'info',
title: 'Notice sent',
message: 'Wanjiru Otieno will receive it by SMS and email.',
})
"
>
info
</nana-button>
<nana-button
size="sm"
variant="secondary"
onclick="
document
.getElementById('toaster-variants')
.toast({
variant: 'success',
title: 'Payment recorded',
message: 'KES 42,000 from Kamau Juma for Unit 4B.',
})
"
>
success
</nana-button>
<nana-button
size="sm"
variant="secondary"
onclick="
document
.getElementById('toaster-variants')
.toast({
variant: 'warning',
title: 'Meter reading late',
message: 'Block C water readings are two days overdue.',
})
"
>
warning
</nana-button>
<nana-button
size="sm"
variant="secondary"
onclick="
document
.getElementById('toaster-variants')
.toast({
variant: 'danger',
title: 'M-Pesa sync failed',
message: 'Retrying in one minute.',
})
"
>
danger
</nana-button>
<nana-button
size="sm"
variant="secondary"
onclick="
document
.getElementById('toaster-variants')
.toast({
variant: 'neutral',
title: 'Draft saved',
message: 'The lease for Unit 7C is saved as a draft.',
})
"
>
neutral
</nana-button>
<nana-toaster id="toaster-variants" max="5"></nana-toaster> Placement
Section titled “Placement”Messages stack in the top-right corner, newest on top. Set placement to
top-start, top, bottom-start, bottom or bottom-end to move them; on a
phone they span the screen at the chosen edge.
A page with a fixed header sets --nana-toaster-offset so messages open below
it rather than over it — this site does exactly that:
nana-toaster { --nana-toaster-offset: calc(4rem + var(--nana-spacing-3));}The toaster lives in the browser’s top layer, so messages show above menus, drawers and dialogs — even a modal opened after them. While a modal is open the page behind it, toasts included, cannot be clicked, so a message’s close button waits until the modal closes.
<nana-button
size="sm"
variant="secondary"
onclick="
document
.getElementById('toaster-top-start')
.toast({
title: 'placement="top-start"',
message: 'Messages stack here.',
})
"
>
top-start
</nana-button>
<nana-button
size="sm"
variant="secondary"
onclick="
document
.getElementById('toaster-top')
.toast({
title: 'placement="top"',
message: 'Messages stack here.',
})
"
>
top
</nana-button>
<nana-button
size="sm"
variant="secondary"
onclick="
document
.getElementById('toaster-top-end')
.toast({
title: 'placement="top-end"',
message: 'Messages stack here.',
})
"
>
top-end
</nana-button>
<nana-button
size="sm"
variant="secondary"
onclick="
document
.getElementById('toaster-bottom-start')
.toast({
title: 'placement="bottom-start"',
message: 'Messages stack here.',
})
"
>
bottom-start
</nana-button>
<nana-button
size="sm"
variant="secondary"
onclick="
document
.getElementById('toaster-bottom')
.toast({
title: 'placement="bottom"',
message: 'Messages stack here.',
})
"
>
bottom
</nana-button>
<nana-button
size="sm"
variant="secondary"
onclick="
document
.getElementById('toaster-bottom-end')
.toast({
title: 'placement="bottom-end"',
message: 'Messages stack here.',
})
"
>
bottom-end
</nana-button>
<nana-toaster id="toaster-top-start" placement="top-start"></nana-toaster>
<nana-toaster id="toaster-top" placement="top"></nana-toaster>
<nana-toaster id="toaster-top-end" placement="top-end"></nana-toaster>
<nana-toaster id="toaster-bottom-start" placement="bottom-start"></nana-toaster>
<nana-toaster id="toaster-bottom" placement="bottom"></nana-toaster>
<nana-toaster id="toaster-bottom-end" placement="bottom-end"></nana-toaster> Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
duration | duration | number | 5000 | How long a message stays, in ms, unless it sets its own; 0 keeps it until dismissed |
label | label | string | 'Notifications' | Accessible name for the landmark |
max | max | number | 3 | The most messages shown at once; the oldest leaves first |
placement | placement | ToasterPlacement | 'top-end' | Which corner or edge of the viewport the stack sits against |
Methods
| Method | Description |
|---|---|
clear(): void | Remove every message |
dismiss(id: string): Promise<void> | Take a message down; resolves once it has left |
toast(init: ToastInit): string | Show a message and return its id |
Events
| Event | Description |
|---|---|
nana-show | A message was added (detail.id) |
nana-hide | A message left, by timeout, dismissal or overflow (detail.id) |
CSS parts
| Part | Description |
|---|---|
::part(base) | The landmark that holds the stack |
::part(list) | The stack of messages |
::part(toast) | One message |
::part(timer) | The bar that runs down until the message leaves |
::part(alert) | The alert that shows one message |
CSS custom properties
| Property | Description |
|---|---|
--nana-toaster-width | Widest a message grows |
--nana-toaster-gap | Space between messages |
--nana-toaster-inset | Distance from the viewport edges |
--nana-toaster-offset | Distance from the top or bottom edge alone, to clear a fixed header or footer; defaults to the inset |
--nana-toaster-z | Stacking order of the toaster |
--nana-toaster-radius | Corner radius of each message |
--nana-toaster-bg | Background of each message |
NanaToaster
| Prop | Type | Default |
|---|---|---|
placement | ToasterPlacement | 'top-right' |
max | number | 3 |
duration | number | 5000 |
label | string |