Toast

Toast notifications provide brief, non-intrusive feedback about an operation. They appear temporarily and can include actions.

import { Toast } from "@ninna-ui/feedback"

pnpm add @ninna-ui/feedback

Requires @ninna-ui/core (auto-installed) + CSS setup.

View source

Usage

Add the Toaster component to your app root, then use the toast function to show notifications.

import { Toaster, toast } from "@ninna-ui/feedback";

// Add Toaster to your app root
export default function App() {
  return (
    <>
      <YourApp />
      <Toaster />
    </>
  );
}

// Use toast anywhere in your app
function MyComponent() {
  return (
    <button onClick={() => toast.create({ title: "Saved!", color: "success" })}>
      Save
    </button>
  );
}

Basic

Basic toast notification with title and description.

Colors

Different toast colors for various notification purposes.

Variants

Visual variants for different styles.

Positions

Each Toaster instance has its own position. Use id on Toaster and toasterId on toast.create() to route toasts to specific positions independently.

With Action

Toast with an action button.

Custom Duration

Control how long toasts stay visible.

Promise

Show loading, success, or error states based on a promise.

Simple Messages

Quick toast with just a string message.

Dismiss

Programmatically dismiss toasts.

API Reference

Complete API documentation for Toast components.

Toaster Props

Prop	Type	Default	Description
`position`	`'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'`	`'bottom-right'`	Position of toasts on screen
`id`	`string`	-	Unique identifier - only toasts created with a matching toasterId will be shown by this Toaster. Omit for the default global Toaster.
`max`	`number`	`5`	Maximum number of visible toasts
`gap`	`number`	`8`	Gap between toasts in pixels
`offset`	`string \| number`	`'1rem'`	Offset from screen edges
`pauseOnHover`	`boolean`	`true`	Pause auto-dismiss when hovering over toasts
`className`	`string`	-	Additional CSS classes for the toast container

Toast Options

Prop	Type	Default	Description
`title`	`ReactNode`	-	Toast title
`description`	`ReactNode`	-	Toast description/message
`color`	`'primary' \| 'secondary' \| 'accent' \| 'neutral' \| 'success' \| 'danger' \| 'warning' \| 'info'`	`'primary'`	Color theme of the toast
`isLoading`	`boolean`	`false`	Show a spinning loader icon. Use with duration: 0 to keep the toast persistent until updated.
`variant`	`'solid' \| 'soft' \| 'outline'`	`'soft'`	Visual variant
`duration`	`number`	`5000`	Duration in milliseconds (0 = persistent)
`closable`	`boolean`	`true`	Whether the toast can be dismissed
`icon`	`ReactNode`	-	Custom icon
`action`	`{ label: string; onClick: () => void; altText?: string }`	-	Action button configuration
`toasterId`	`string`	-	Route this toast to a specific Toaster by its id. Omit to send to the default global Toaster.

Toast Methods

Prop	Type	Default	Description
`toast.create(options)`	`string`	-	Create a new toast. Pass color to indicate type (e.g. success, danger). Returns the toast ID.
`toast.dismiss(id?)`	`void`	-	Dismiss a specific toast by ID, or dismiss all toasts if no ID is provided
`toast.dismissAll()`	`void`	-	Dismiss all toasts
`toast.update(id, options)`	`void`	-	Update an existing toast by ID
`toast.promise(promise, options)`	`Promise<T>`	-	Show a loading toast while the promise is pending, then update to success or danger on resolution

Accessibility

ARIA Support

role="status": Used for non-critical toasts (neutral, primary, secondary, accent, success, info, warning)
role="alert": Used for error toasts (danger) to ensure immediate announcement
aria-live="polite": Default for non-critical notifications
aria-live="assertive": Automatically set for error notifications
aria-atomic="true": Ensures the entire toast is announced

Keyboard Navigation

Escape: Dismisses the most recent toast
Tab: Navigate between toast elements (action button, close button)
Enter/Space: Activate focused button

Focus Management

Toasts are focusable with tabIndex=0
Focus is not stolen when toasts appear
Close buttons have proper aria-label
Action buttons include aria-label with altText

Motion & Timing

prefers-reduced-motion: Animations are disabled for users who prefer reduced motion
Pause on hover: Auto-dismiss pauses when hovering over toasts
Pause on focus: Auto-dismiss pauses when toast is focused