Toast

Sonner-inspired toast notification system with GSAP animations, smart stacking, and accessibility features

Installation

Install the Toast component using the nocta-ui CLI:

Terminal

npx nocta-ui add toast

Then import the components you need:

Import

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

Setup

Add the Toaster component to your app to enable toast notifications:

Toaster Setup

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

function App() {
  return (
    <>
      <YourApp />
      <Toaster />
    </>
  );
}

Basic Usage

Simple Toast

Variants

The Toast component supports multiple variants: default, success, warning, and destructive.

Positions

Toasts can be positioned in 6 different locations on the screen. Each position manages its own stack of toasts independently.

Click the buttons to see toasts appear in different positions:

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

Toast with Actions

Add action buttons to your toast notifications for user interaction.

Stacked Toasts

The toast system supports smart stacking with a maximum of 3 visible toasts. New toasts push older ones up with scale and blur effects.

Persistent Toast

Create persistent toasts that don't auto-close by setting duration to 0.

Custom Duration

Customize how long toasts remain visible by setting a custom duration in milliseconds.

Dismiss All

You can dismiss all active toasts programmatically using the dismissAll function.

Press Escape to close the topmost toast
Toasts are focusable and announced to screen readers
Full keyboard navigation support for action buttons

Customization

Custom Styling

All toast components accept className props for custom styling:

Custom Toast Styling

toast({
  title: 'Custom Toast',
  description: 'This toast has custom styling.',
  className: 'border-l-4 border-l-blue-500'
});

Props

ToastData Interface

Prop	Type	Default	Description
`title`	`string`	—	Toast title
`description`	`string`	—	Toast description
`variant`	`'default' \| 'success' \| 'warning' \| 'destructive'`	`'default'`	Toast style variant
`className`	`string`	—	Custom CSS classes for styling
`position`	`'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'`	`'bottom-center'`	Toast position on screen
`duration`	`number`	`5000`	Auto-close duration in ms (0 = persistent)
`action`	`{ label: string; onClick: () => void }`	—	Action button configuration
`shouldClose`	`boolean`	false	Flag for programmatic closing with animation

Toast API

The toast function and its methods:

Function	Type	Description
`toast()`	`(data: ToastData \| string) => string`	Show a default toast notification
`toast.success()`	`(data: Omit<ToastData, 'variant'> \| string) => string`	Show a success toast
`toast.warning()`	`(data: Omit<ToastData, 'variant'> \| string) => string`	Show a warning toast
`toast.error()`	`(data: Omit<ToastData, 'variant'> \| string) => string`	Show an error toast
`toast.dismiss()`	`(id: string) => void`	Dismiss a specific toast
`toast.dismissAll()`	`() => void`	Dismiss all active toasts

Simple String Usage

You can also pass a simple string for quick notifications:

Simple String Toasts

toast('Simple message');
toast.success('Operation successful!');
toast.warning('Please be careful');
toast.error('Something went wrong');