ToastUpdated

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

Expanded Stack

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-button - 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
• Entering: [data-entering] - Applied on first paint of a new toast
• Exiting: [data-exiting] - Applied while a closing toast plays its exit transition
• Expanded: [data-expanded] - Applied to every toast while the stack is expanded
• Hidden: [data-hidden] - Applied to toasts beyond maxVisibleToasts

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. The returned id lets the action close its own toast.
const eventId = 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: () => toast.close(eventId),
  },
  indicator: <CustomIcon />,
});

// Update an existing toast in place (keeps its position in the stack).
// Options you omit are inherited, so pass `timeout` to start a countdown
// on a toast that was created persistent.
const id = toast("Saving…", { timeout: 0 });
toast.update(id, "Saved", { variant: "success", timeout: 4000 });

// Promise support (automatically shows loading spinner). The loading toast
// updates in place when the promise settles — same toast, same stack
// position; the auto-dismiss countdown starts at that point.
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, update in place and start the auto-dismiss countdown
toast.update(loadingId, "Event created", { variant: "success", timeout: 4000 });

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

toast Options

toast.promise Options

Accessibility

Each toast implements the WAI-ARIA alertdialog pattern, grouped inside a labeled landmark region:

• Landmark region: Toasts render in a labeled landmark reachable with F6; Alt + T moves focus straight to it. The hotkey is configurable via the hotkey prop and can be disabled by passing an empty array, and the region label can be overridden with aria-label
• Keyboard: Tab reaches the controls of visible toasts, Escape collapses the expanded stack, and dismissing a focused toast moves focus to the nearest remaining toast
• Screen readers: Each toast uses role="alertdialog" with its title and description linked; new toasts are announced automatically
• Timers: Auto-dismiss pauses while the stack is hovered or focused, and while the page is in a background tab

Related Components