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 { useToast, ToastProvider } from '@/components/ui/toast';

Setup

Wrap your app with the ToastProvider to enable toast notifications:

Toast Provider Setup

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

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

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
`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

useToast Hook

The useToast hook returns:

Function	Type	Description
`toast`	`(data: ToastData) => string`	Show a toast notification
`dismiss`	`(id: string) => void`	Dismiss a specific toast
`dismissAll`	`() => void`	Dismiss all active toasts