Toast

The Toast component provides lightweight, non-intrusive notification messages. Built on Radix UI Toast, it handles auto-dismiss, swipe-to-close, keyboard navigation, and screen reader announcements. Supports both declarative JSX and an imperative API (toast.success("Saved!")).

Import

import {
  // Imperative API
  toast,
  Toaster,

  // Declarative components
  Toast,
  ToastProvider,
  ToastViewport,
  ToastTitle,
  ToastDescription,
  ToastClose,
  ToastAction,
} from '@nim-ui/components';

Quick Start (Imperative API)

The easiest way to use toasts. Place <Toaster /> once at your app root, then call toast() from anywhere.

Basic Toast

View Code

import { Toaster, toast } from '@nim-ui/components';

function App() {
  return (
    <>
      <button onClick={() => toast({ title: 'Hello!', description: 'This is a toast.' })}>
        Show Toast
      </button>
      <Toaster />
    </>
  );
}

Variants

Use shorthand functions for common notification types. Each sets the appropriate color scheme automatically.

Toast Variants

View Code

toast.success('Changes saved successfully');
toast.error('Something went wrong');
toast.warning('Please check your input');
toast.info('New version available');

With Action

Add an action button inside the toast for undo or retry patterns.

Toast with Action

View Code

toast({
  title: 'Item deleted',
  description: 'The item has been moved to trash.',
  action: {
    label: 'Undo',
    altText: 'Undo the delete action',
    onClick: () => toast.success('Item restored'),
  },
});

Positioning

Control where toasts appear on screen via the position prop on Toaster.

<Toaster position="top-right" />
<Toaster position="top-center" />
<Toaster position="bottom-left" />
<Toaster position="bottom-center" />

Available positions: top-right, top-left, top-center, bottom-right, bottom-left, bottom-center.

Duration

Toasts auto-dismiss after 5 seconds by default. Override per-toast or globally.

// Global default: 3 seconds
<Toaster duration={3000} />

// Per-toast override
toast({ title: 'Quick!', duration: 2000 });

// Persistent toast (no auto-dismiss)
toast({ title: 'Action required', duration: Infinity });

Programmatic Dismiss

Use the returned id to dismiss a specific toast, or clear all at once.

const id = toast.success('Uploading...');

// Dismiss specific toast
toast.dismiss(id);

// Clear all toasts
toast.clear();

Declarative API

For full control, use the compound components directly.

<ToastProvider duration={5000} swipeDirection="right">
  <Toast variant="success">
    <ToastTitle>Saved!</ToastTitle>
    <ToastDescription>Your changes have been saved.</ToastDescription>
    <ToastAction altText="Undo the save">Undo</ToastAction>
    <ToastClose />
  </Toast>
  <ToastViewport position="bottom-right" />
</ToastProvider>

Component Architecture

Component	Description
Toaster	Convenience component — combines Provider + Viewport + renders toasts from store
toast()	Imperative function to create toasts from anywhere in your code
ToastProvider	Radix Toast.Provider for context management
ToastViewport	Fixed-position container with ARIA live region
Toast	Individual toast with variant styling and animations
ToastTitle	Title text
ToastDescription	Description text
ToastClose	Close button with accessible label
ToastAction	Action button (e.g., Undo)

Props

Toaster

Name	Type	Default	Description
position	'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center'	'bottom-right'	Position of the toast viewport on screen
duration	number	5000	Default auto-dismiss duration in milliseconds
swipeDirection	'right' | 'left' | 'up' | 'down'	'right'	Swipe direction to dismiss toasts

Toast

Name	Type	Default	Description
variant	'default' | 'success' | 'error' | 'warning' | 'info'	'default'	Visual style variant
duration	number	-	Override auto-dismiss duration for this toast
onOpenChange	(open: boolean) => void	-	Callback when the toast open state changes
className	string	-	Additional CSS classes

ToastViewport

Name	Type	Default	Description
position	'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center'	'bottom-right'	Position on screen
className	string	-	Additional CSS classes

ToastAction

Name	Type	Default	Description
altText *	string	-	Accessible description of the action for screen readers
onClick	() => void	-	Click handler for the action

toast() API

// Main function
toast(options: ToastOptions): string  // returns toast id

// Shorthand functions
toast.success(title: string): string
toast.error(title: string): string
toast.warning(title: string): string
toast.info(title: string): string

// Management
toast.dismiss(id: string): void
toast.clear(): void

ToastOptions

Field	Type	Required	Description
title	string	No	Toast title text
description	string	No	Toast description text
variant	'default' | 'success' | 'error' | 'warning' | 'info'	No	Visual variant (default: 'default')
duration	number	No	Auto-dismiss duration in ms
action	{ label, altText, onClick }	No	Action button configuration

Accessibility

Built on Radix UI Toast with full accessibility support:

• ARIA live region: ToastViewport renders as a live region for screen reader announcements
• Keyboard dismiss: Press Escape to close the focused toast
• Swipe dismiss: Swipe gesture support for touch devices
• Focus navigation: Tab through interactive elements within a toast
• Close button label: ToastClose includes aria-label for screen readers
• Reduced motion: Respects prefers-reduced-motion media query

Keyboard Support

Key	Action
Escape	Closes the focused toast
Tab	Moves focus to next interactive element
Shift + Tab	Moves focus to previous interactive element

Related Components

• Modal — Dialog overlay for focused interactions
• Drawer — Side panel overlay