ToastUpdated

Import

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

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>
  );
}

Usage

"use client";

import {Persons} from "@gravity-ui/icons";
import {Button, toast} from "@heroui/react";

Simple Toasts

"use client";

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

export function Simple() {

Variants

"use client";

import {HardDrive, Persons} from "@gravity-ui/icons";
import {Button, toast} from "@heroui/react";

Custom Indicators

"use client";

import {Star} from "@gravity-ui/icons";
import {Button, toast} from "@heroui/react";

Promise & Loading

"use client";

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

const uploadFile = (): Promise<{filename: string; size: number}> => {

Callbacks

"use client";

import {Button, toast} from "@heroui/react";
import React from "react";

Placements

"use client";

import type {ToastVariants} from "@heroui/react";

import {Button, Toast, ToastQueue} from "@heroui/react";

Custom Toast Rendering

"use client";

import type {ToastContentValue} from "@heroui/react";

import {

Custom Queues

"use client";

import {Button, Toast, ToastQueue} from "@heroui/react";

export function CustomQueue() {

Anatomy

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

Styling

Passing Tailwind CSS classes

<Toast.Provider className="bottom-8 right-8" placement="bottom end" />

Customizing the component classes

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;
  }
}

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 Props

Toast Props

Toast.Content Props

Toast.Indicator Props

Toast.Title Props

Toast.Description Props

Toast.ActionButton Props

Toast.CloseButton Props

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