Skip to content
Nana UI

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.

View .md Download

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.

Record payment Fail a sync
npm install @nana-tec/ui-components

Or copy the source in and own it:

npx @nana-tec/ui add toaster --framework web-components
npx @nana-tec/ui add toaster --framework svelte

Lands in src/lib/components/ui/toaster/ as NanaToaster.svelte, styled with Tailwind classes that resolve to the design tokens. Requires Tailwind v4.

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.

FieldDefaultDescription
message—The text of the message
title—A bold heading above it
variantinfoinfo, success, warning, danger or neutral, as on alert
durationthe toaster’sHow long it stays, in ms; 0 keeps it until dismissed
dismissibletrueWhether it has a close button
idgeneratedReuse one to replace a message

The variant colours the icon and the countdown bar; the card itself stays on the page surface.

info success warning danger neutral

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.

top-start top top-end bottom-start bottom bottom-end

Properties

PropertyAttributeTypeDefaultDescription
durationdurationnumber5000How long a message stays, in ms, unless it sets its own; 0 keeps it until dismissed
labellabelstring'Notifications'Accessible name for the landmark
maxmaxnumber3The most messages shown at once; the oldest leaves first
placementplacementToasterPlacement'top-end'Which corner or edge of the viewport the stack sits against

Methods

MethodDescription
clear(): voidRemove every message
dismiss(id: string): Promise<void>Take a message down; resolves once it has left
toast(init: ToastInit): stringShow a message and return its id

Events

EventDescription
nana-showA message was added (detail.id)
nana-hideA message left, by timeout, dismissal or overflow (detail.id)

CSS parts

PartDescription
::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

PropertyDescription
--nana-toaster-widthWidest a message grows
--nana-toaster-gapSpace between messages
--nana-toaster-insetDistance from the viewport edges
--nana-toaster-offsetDistance from the top or bottom edge alone, to clear a fixed header or footer; defaults to the inset
--nana-toaster-zStacking order of the toaster
--nana-toaster-radiusCorner radius of each message
--nana-toaster-bgBackground of each message

NanaToaster

PropTypeDefault
placementToasterPlacement'top-right'
maxnumber3
durationnumber5000
labelstring