Core Toast Functions

/**
 * Creates a basic toast notification
 * @param message - The message to display (string or React element)
 * @param options - Optional configuration for the toast
 * @returns Unique identifier for the created toast
 */
function toast(message: string | React.ReactNode, options?: ExternalToast): string | number;

import { toast } from "sonner";

// Simple text message
toast("Hello World!");

// React element message
toast(<div>Custom <strong>HTML</strong> content</div>);

// With options
toast("Custom duration", { duration: 5000 });

// With description
toast("Main message", { 
  description: "Additional details about this notification" 
});

// With action button
toast("Do something", {
  action: {
    label: "Undo",
    onClick: () => console.log("Undo clicked")
  }
});

/**
 * Creates a success toast notification
 * @param message - The success message to display
 * @param options - Optional configuration for the toast
 * @returns Unique identifier for the created toast
 */
function toast.success(message: string | React.ReactNode, options?: ExternalToast): string | number;

import { toast } from "sonner";

// Simple success message
toast.success("Operation completed successfully!");

// Success with description
toast.success("User created", { 
  description: "New user has been added to the system" 
});

// Success with custom duration
toast.success("Saved!", { duration: 2000 });

/**
 * Creates an error toast notification
 * @param message - The error message to display
 * @param options - Optional configuration for the toast
 * @returns Unique identifier for the created toast
 */
function toast.error(message: string | React.ReactNode, options?: ExternalToast): string | number;

import { toast } from "sonner";

// Simple error message
toast.error("Something went wrong!");

// Error with description
toast.error("Failed to save", { 
  description: "Please check your internet connection and try again" 
});

// Error with action button
toast.error("Upload failed", {
  action: {
    label: "Retry",
    onClick: () => retryUpload()
  }
});

/**
 * Creates an info toast notification
 * @param message - The info message to display
 * @param options - Optional configuration for the toast
 * @returns Unique identifier for the created toast
 */
function toast.info(message: string | React.ReactNode, options?: ExternalToast): string | number;

import { toast } from "sonner";

// Simple info message
toast.info("New update available");

// Info with description
toast.info("System maintenance", { 
  description: "Scheduled maintenance will begin at 2 AM EST" 
});

/**
 * Creates a warning toast notification
 * @param message - The warning message to display
 * @param options - Optional configuration for the toast
 * @returns Unique identifier for the created toast
 */
function toast.warning(message: string | React.ReactNode, options?: ExternalToast): string | number;

import { toast } from "sonner";

// Simple warning message
toast.warning("Low disk space");

// Warning with description
toast.warning("Unsaved changes", { 
  description: "You have unsaved changes that will be lost" 
});

/**
 * Creates a loading toast notification with spinner
 * @param message - The loading message to display
 * @param options - Optional configuration for the toast
 * @returns Unique identifier for the created toast
 */
function toast.loading(message: string | React.ReactNode, options?: ExternalToast): string | number;

import { toast } from "sonner";

// Simple loading message
const loadingId = toast.loading("Uploading file...");

// Later, update or dismiss the loading toast
setTimeout(() => {
  toast.success("File uploaded successfully!", { id: loadingId });
}, 3000);

// Loading with custom message
toast.loading("Processing your request...");

/**
 * Creates a message toast notification (alias for default toast)
 * @param message - The message to display
 * @param options - Optional configuration for the toast
 * @returns Unique identifier for the created toast
 */
function toast.message(message: string | React.ReactNode, options?: ExternalToast): string | number;

/**
 * Dismisses toast notifications
 * @param id - Optional ID of specific toast to dismiss. If omitted, dismisses all toasts
 * @returns The ID that was dismissed, or undefined if dismissing all
 */
function toast.dismiss(id?: string | number): string | number | undefined;

import { toast } from "sonner";

// Dismiss specific toast
const toastId = toast("This will be dismissed");
setTimeout(() => {
  toast.dismiss(toastId);
}, 2000);

// Dismiss all toasts
toast.dismiss();

// Common pattern: dismiss after action
toast("File uploaded", {
  action: {
    label: "View",
    onClick: () => {
      openFile();
      toast.dismiss(); // Clear all toasts when navigating
    }
  }
});

interface ExternalToast {
  /** Custom ID for the toast (auto-generated if not provided) */
  id?: string | number;
  /** Custom icon to display instead of the default type icon */
  icon?: React.ReactNode;
  /** Rich colors mode for enhanced visual styling */
  richColors?: boolean;
  /** Invert the color scheme for dark backgrounds */
  invert?: boolean;
  /** Show close button on the toast */
  closeButton?: boolean;
  /** Whether the toast can be dismissed by user interaction */
  dismissible?: boolean;
  /** Additional description text displayed below the main message */
  description?: (() => React.ReactNode) | React.ReactNode;
  /** Duration in milliseconds before auto-dismiss (default: 4000) */
  duration?: number;
  /** Action button configuration */
  action?: Action | React.ReactNode;
  /** Cancel button configuration */
  cancel?: Action | React.ReactNode;
  /** Callback fired when toast is dismissed */
  onDismiss?: (toast: ToastT) => void;
  /** Callback fired when toast auto-closes */
  onAutoClose?: (toast: ToastT) => void;
  /** Custom styles for cancel button */
  cancelButtonStyle?: React.CSSProperties;
  /** Custom styles for action button */
  actionButtonStyle?: React.CSSProperties;
  /** Custom styles for the toast container */
  style?: React.CSSProperties;
  /** Disable default styling */
  unstyled?: boolean;
  /** Custom CSS class for the toast */
  className?: string;
  /** Custom CSS classes for toast elements */
  classNames?: ToastClassnames;
  /** Custom CSS class for description text */
  descriptionClassName?: string;
  /** Override global position for this specific toast */
  position?: Position;
}

interface Action {
  /** Text or React element to display on the button */
  label: React.ReactNode;
  /** Click handler for the button */
  onClick: (event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void;
  /** Custom styles for this action button */
  actionButtonStyle?: React.CSSProperties;
}

// Undo action
toast("Item deleted", {
  action: {
    label: "Undo",
    onClick: () => restoreItem()
  }
});

// Multiple buttons using cancel and action
toast("Confirm deletion?", {
  cancel: {
    label: "Cancel",
    onClick: () => console.log("Cancelled")
  },
  action: {
    label: "Delete",
    onClick: (event) => {
      deleteItem();
      // event.preventDefault() prevents auto-dismiss
    }
  }
});

// Toast that doesn't auto-dismiss
toast("Important message", { duration: Infinity });

// Loading toast (automatically persistent)
const loadingId = toast.loading("Processing...");

// Update the persistent toast later
toast.success("Done!", { id: loadingId });

// Custom styles
toast.success("Styled toast", {
  style: {
    background: "green",
    color: "white",
    border: "none"
  },
  className: "my-custom-toast"
});

// Custom class names for elements
toast("Detailed styling", {
  classNames: {
    toast: "custom-toast-container",
    title: "custom-title",
    description: "custom-description"
  }
});