# Toast · HeroUI

> Migration guide for Toast from HeroUI v2 to v3

- Page: https://jiguang132.com/systems/heroui/docs/migration/toast
- Based on: HeroUI documentation (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

> 
  Refer to the [v3 Toast documentation](/systems/heroui/docs/components/toast) 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:

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

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

---

Index of all JGuang resources: https://jiguang132.com/llms.txt