Toast

A succinct message that is displayed temporarily to provide feedback about an action or event.

Component Source

View the source code for the toast component.

$lib/components/ui/toast/

Installation

npx nnuikit add toast

import { Toaster, toast } from "$lib/components/ui/toast";

Quick Start

<script lang="ts">
  import { Button } from "$lib/components/ui/button";
  import { Toaster, toast } from "$lib/components/ui/toast";

  function showNotification() {
    toast.success("Changes saved successfully!");
  }
</script>

<!-- Add Toaster to your root +layout.svelte (once) -->
<Toaster position="top-right" mode="inline" />

<!-- Trigger toast from anywhere -->
<Button onclick={showNotification}>Show Toast</Button>

Interactive Playground

Customize variant and mode to see how toasts appear. Position is set on the Toaster in the root layout.

Click the button to trigger a inline toast.

toast.add({
  title: "Notification Title",
  description: "Your notification message here",
  variant="success",
});

Variant

Mode

Visual Variants

Explore different visual styles for toasts.

Success

Error

Warning

Info

Brand (Custom)

Inline vs Expanded

Two layout modes matching the Figma design system. Inline is a compact single-row notification. Expanded is a multi-row card with a left color accent border and action buttons below the description.

Inline Mode

toast.add({
  title: "Alert title",
  description: "Alert content",
  variant: "success",
  mode: "inline",
});

Expanded Mode

toast.add({
  title: "Alert title",
  description: "Alert content",
  variant: "success",
  mode: "expanded",
  action: { label: "Button", onClick: () => {} },
});

Custom Toast

Use the toast.custom() method for complete control over all toast properties.

Full Customization Example

The custom method gives you complete control over every aspect of the toast notification.

toast.custom({
  title: "Custom Notification",
  description: "Fully customizable toast with all options",
  variant: "brand",
  duration: 1000,
  dismissible: true,
  action: {
    label: "View Details",
    onClick: () => console.log("Action clicked")
  },
  onDismiss: () => console.log("Toast dismissed")
});

Multiple Toast

The toast system handles multiple notifications gracefully with stacking and animations.

Stacking Behavior

Click to trigger a sequence of notifications to see how they stack.


{
    toast.success("First notification");
    setTimeout(() => toast.info("Second notification"), 200);
    setTimeout(() => toast.warning("Third notification"), 400);
}

Accessibility

Screen reader: role="status" and aria-live announce toasts

Auto-dismiss: configurable duration, pause on hover

Keyboard: Escape or click dismiss button to close

Position: fixed positioning doesn't interfere with page flow

API Reference

Toaster Component

Prop	Type	Default	Description
`position`	`'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'`	'top-right'	Position of the toast container on screen.
`mode`	`'inline' \| 'expanded'`	'inline'	Default mode for all toasts. 'inline' is compact single-row, 'expanded' is multi-row with left accent border. Individual toasts can override.
`maxToasts`	`number`	4	Maximum number of visible toasts at once.
`class`	`string`	-	Additional CSS classes for the container.

Toast Data

Prop	Type	Default	Description
`title`	`string`	-	Optional title for the toast.
`description`	`string`	-	Main message content.
`variant`	`'default' \| 'brand' \| 'success' \| 'destructive' \| 'warning' \| 'info'`	'default'	Visual style variant.
`mode`	`'inline' \| 'expanded'`	'inline'	Toast layout mode. 'inline' is compact single-row. 'expanded' is multi-row with left accent border and action buttons below.
`duration`	`number`	5000	Auto-dismiss duration in ms. Set to 0 for persistent.
`dismissible`	`boolean`	true	Whether the toast can be manually dismissed.
`action`	`{ label: string; onClick: () => void }`	-	Optional action button configuration.
`onDismiss`	`() => void`	-	Callback when toast is dismissed.

Toast Methods

Prop	Type	Default	Description
`toast.add(data)`	`(data: ToastData) => string`	-	Add a new toast and return its ID.
`toast.success(message, options?)`	`(message: string, options?: Partial<ToastData>) => string`	-	Show a success toast.
`toast.error(message, options?)`	`(message: string, options?: Partial<ToastData>) => string`	-	Show an error toast.
`toast.warning(message, options?)`	`(message: string, options?: Partial<ToastData>) => string`	-	Show a warning toast.
`toast.info(message, options?)`	`(message: string, options?: Partial<ToastData>) => string`	-	Show an info toast.
`toast.custom(options)`	`(options: Omit<ToastData, 'id'>) => string`	-	Create a fully customized toast with all properties.
`toast.dismiss(id)`	`(id: string) => void`	-	Dismiss a specific toast by ID.
`toast.dismissAll()`	`() => void`	-	Dismiss all active toasts.

Built on bits-ui — Toast uses primitives from bits-ui for portal rendering and ARIA attributes. For the full primitive API, see the bits-ui Toast docs.