Toast

Refer to the v3 Toast documentation for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.

Structure Changes

In v2, Toast used a provider and hook pattern:

import { ToastProvider, useToast } from "@heroui/react";

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

function MyComponent() {
  const { toast } = useToast();

  return (
    <button onClick={() => toast.show("Hello!")}>
      Show Toast
    </button>
  );
}

In v3, Toast uses a provider component and a global toast() function:

import { Toast } from "@heroui/react";

function App() {
  return (
    <>
      <Toast.Provider />
      <MyComponent />
    </>
  );
}

function MyComponent() {
  return (
    <button onClick={() => toast("Hello!")}>
      Show Toast
    </button>
  );
}

Key Changes

1. Provider Pattern

v2: Required ToastProvider wrapper
v3: Uses Toast.Provider component (can be placed anywhere)

2. Hook → Function

v2: Used useToast() hook
v3: Uses toast() function directly

3. API Changes

v2: Used toast.show() method
v3: toast() is a function with helper methods (toast.success(), toast.danger(), etc.)

4. Variant Names

v2: Variants like success, error, warning, info
v3: Variants: default, accent, success, warning, danger

5. Compound Component Structure

v3: Toast uses compound components for custom rendering:

Toast - Main toast container
Toast.Content - Content wrapper
Toast.Title - Title text
Toast.Description - Description text
Toast.Indicator - Icon/indicator
Toast.CloseButton - Close button
Toast.ActionButton - Action button

const { toast } = useToast();

toast.show({
  title: "Success",
  description: "Your changes have been saved",
  variant: "success"
});

import { toast } from "@heroui/react";

toast.success("Success", {
  description: "Your changes have been saved"
});

Helper Methods for Variants

const { toast } = useToast();

toast.show({ variant: "success", title: "Success" });
toast.show({ variant: "error", title: "Error" });
toast.show({ variant: "warning", title: "Warning" });
toast.show({ variant: "info", title: "Info" });

import { toast } from "@heroui/react";

toast.success("Success");
toast.danger("Error");
toast.warning("Warning");
toast.info("Info");

Promise Support

const { toast } = useToast();

const handleAsync = async () => {
  try {
    await someAsyncOperation();
    toast.show({ title: "Success", variant: "success" });
  } catch {
    toast.show({ title: "Error", variant: "error" });
  }
};

import { toast } from "@heroui/react";

const handleAsync = async () => {
  toast.promise(someAsyncOperation(), {
    loading: "Processing...",
    success: "Operation completed!",
    error: "Operation failed"
  });
};

Custom Toast Rendering

const { toast } = useToast();

toast.show({
  title: "Custom",
  render: (toast) => (
    <div>Custom content</div>
  )
});

import { Toast, ToastContent, ToastTitle } from "@heroui/react";

<Toast.Provider>
  {({ toast: toastItem }) => (
    <Toast toast={toastItem}>
      <ToastContent>
        <ToastTitle>Custom content</ToastTitle>
      </ToastContent>
    </Toast>
  )}
</Toast.Provider>

Summary

Replace ToastProvider with Toast.Provider
Replace useToast() hook with toast() function
Update variant names (error → danger, info → accent)
Use helper methods: toast.success(), toast.danger(), etc.
Use toast.promise() for async operations
Compound component structure for custom rendering
Better TypeScript support and queue management