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

6. Promise Support

v3: Built-in promise support with toast.promise() for handling async operations

Migration Examples

Toast with Title and Description

v2

```tsx
const { toast } = useToast();

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

v3

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

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

Helper Methods for Variants

v2

```tsx
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" });
```

v3

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

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

Promise Support

v2

```tsx
const { toast } = useToast();

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

v3

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

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

Custom Toast Rendering

v2

```tsx
const { toast } = useToast();

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

v3

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