Toast

Usage

import { Toast, toast } from '@heroui/react';

Anatomy

<Toast.Provider>
  <Toast>
    <Toast.Indicator />
    <Toast.Content>
      <Toast.Title />
      <Toast.Description />
    </Toast.Content>
    <Toast.ActionButton />
    <Toast.CloseButton />
  </Toast>
</Toast.Provider>

Examples

Variants

Placements

Simple Toasts

Custom Indicators

Custom Toast Rendering

Promise & Loading

Callbacks

Custom Queues

Setup

Render the provider in the root of your app.

import { Toast, Button, toast } from '@heroui/react';

function App() {
  return (
    <div>
      <Toast.Provider />
      <Button onPress={() => toast("Simple message")}>
        Show toast
      </Button>
    </div>
  );
}

Customization

Tailwind CSS

Global CSS

To customize the Toast component classes, you can use the @layer components directive. Learn more.

@layer components {
  .toast {
    @apply rounded-xl shadow-lg;
  }

  .toast__content {
    @apply gap-2;
  }
}

Styling Reference

HeroUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

CSS Classes

The Toast component uses these CSS classes (View source styles):

Base Classes

• .toast - Base toast container
• .toast__region - Toast region container
• .toast__content - Content wrapper for title and description
• .toast__indicator - Icon/indicator container
• .toast__title - Toast title text
• .toast__description - Toast description text
• .toast__action - Action button container
• .toast__close - Close button container

Variant Classes

• .toast--default - Default gray variant
• .toast--accent - Accent blue variant
• .toast--success - Success green variant
• .toast--warning - Warning yellow/orange variant
• .toast--danger - Danger red variant

Interactive States

The component supports various states:

• Frontmost: [data-frontmost] - Applied to the topmost visible toast
• Index: [data-index] - Applied based on toast position in stack
• Placement: [data-placement="*"] - Applied based on toast region placement

API Reference

Toast.Provider

Toast

Toast.Content

Toast.Indicator

Toast.Title

Toast.Description

Toast.ActionButton

Toast.CloseButton

ToastQueue

A ToastQueue manages the state for a <Toast.Provider>. The state is stored outside React so you can trigger toasts from anywhere in your application.

Constructor Options

Methods

toast Function

The default toast function provides convenient methods for showing toasts:

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

// Basic toast (auto-dismisses after 4 seconds by default)
toast("Event has been created");

// Variant methods (also auto-dismiss after 4 seconds by default)
toast.success("File saved");
toast.info("New update available");
toast.warning("Please check your settings");
toast.danger("Something went wrong");

// With options
toast("Event has been created", {
  description: "Your event has been scheduled for tomorrow",
  variant: "default",
  timeout: 5000, // Custom timeout: 5 seconds
  onClose: () => console.log("Closed"),
  actionProps: {
    children: "View",
    onPress: () => {},
  },
  indicator: <CustomIcon />,
});

// Promise support (automatically shows loading spinner)
toast.promise(
  uploadFile(),
  {
    loading: "Uploading file...",
    success: (data) => `File ${data.filename} uploaded`,
    error: "Failed to upload file",
  }
);

// Manual loading state (persistent toast - no auto-dismiss)
const loadingId = toast("Creating event...", {
  isLoading: true,
  timeout: 0, // Persistent toast that doesn't auto-dismiss
});

// Later, close and show result
toast.close(loadingId);
toast.success("Event created");

// Queue methods
toast.close(key);
toast.clear();
toast.pauseAll();
toast.resumeAll();

toast Options

toast.promise Options

Related Components