ProComponents, templates & AI tooling
HeroUI
27.7k
快速开始
组件
发布说明
迁移

Toast 轻提示

向用户展示临时通知与消息，支持自动消失与可定制的放置位置。

FigmaStorybookReact Aria源代码样式源代码

引入

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

设置

在应用根部渲染 Provider。

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

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

用法

"use client";

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

简单 Toast

"use client";

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

export function Simple() {

变体

"use client";

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

自定义指示器

"use client";

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

Promise 与加载中

使用 toast.promise()

自动处理加载、成功和错误状态

手动加载状态

使用 isLoading 属性手动控制加载状态

"use client";

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

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

回调

关闭历史

尚无已关闭的 Toast。请尝试关闭上方的 Toast！

"use client";

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

放置位置

"use client";

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

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

自定义 Toast 渲染

"use client";

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

import {

自定义队列

"use client";

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

export function CustomQueue() {

组件结构

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

样式

传入 Tailwind CSS 类

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

自定义组件类

要自定义 Toast 的组件类，可使用 @layer components 指令。
了解更多。

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

  .toast__content {
    @apply gap-2;
  }
}

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

Toast 使用以下 CSS 类（查看源码样式）：

基础类

  • .toast — Toast 根容器
  • .toast__region — Toast 区域容器
  • .toast__content — 包裹标题与说明的内容容器
  • .toast__indicator — 图标/指示器容器
  • .toast__title — Toast 标题文本
  • .toast__description — Toast 说明文本
  • .toast__action — 操作按钮容器
  • .toast__close — 关闭按钮容器

变体类

  • .toast--default — 默认灰色变体
  • .toast--accent — 强调蓝色变体
  • .toast--success — 成功绿色变体
  • .toast--warning — 警告黄/橙色变体
  • .toast--danger — 危险红色变体

交互状态

组件支持多种状态：

  • 最前：[data-frontmost] — 应用于堆叠中最上层可见的 Toast
  • 索引：[data-index] — 基于 Toast 在堆叠中的位置
  • 放置：[data-placement="*"] — 基于 Toast 区域的放置位置

API 参考

Toast.Provider Props

Prop类型默认值描述
placement"top start" | "top" | "top end" | "bottom start" | "bottom" | "bottom end""bottom"Toast 区域的放置位置
gapnumber12Toast 之间的间距（像素）
maxVisibleToastsnumber3同时最多显示的 Toast 数量
scaleFactornumber0.05堆叠 Toast 的缩放系数（0–1）
widthnumber | string460Toast 宽度（像素或 CSS 值）
queueToastQueue<T>-自定义 Toast 队列实例
childrenReactNode | ((props: {toast: QueuedToast<T>}) => ReactNode)-自定义渲染函数或子节点
classNamestring-附加的 CSS 类

Toast Props

Prop类型默认值描述
toastQueuedToast<T>-来自队列的 Toast 数据（必填）
variant"default" | "accent" | "success" | "warning" | "danger""default"Toast 的视觉变体
placementToastVariants["placement"]-放置位置（继承自 Provider）
scaleFactornumber-缩放系数（继承自 Provider）
classNamestring-附加的 CSS 类
childrenReactNode-Toast 内容（ToastContent、ToastIndicator 等）

Toast.Content Props

Prop类型默认值描述
childrenReactNode-内容（通常为 ToastTitle 与 ToastDescription）
classNamestring-附加的 CSS 类

Toast.Indicator Props

Prop类型默认值描述
variantToastVariants["variant"]-默认图标的变体
childrenReactNode-自定义指示图标（默认使用变体图标）
classNamestring-附加的 CSS 类

Toast.Title Props

Prop类型默认值描述
childrenReactNode-标题文本
classNamestring-附加的 CSS 类

Toast.Description Props

Prop类型默认值描述
childrenReactNode-说明文本
classNamestring-附加的 CSS 类

Toast.ActionButton Props

Prop类型默认值描述
childrenReactNode-操作按钮内容
classNamestring-附加的 CSS 类
All Button props--接受 Button 组件的全部 props

Toast.CloseButton Props

Prop类型默认值描述
classNamestring-附加的 CSS 类
All CloseButton props--接受 CloseButton 组件的全部 props

ToastQueue

ToastQueue 用于管理 <Toast.Provider> 的状态。状态存放在 React 之外，因此你可以在应用的任意位置触发 Toast。

构造选项

Option类型默认值描述
maxVisibleToastsnumber3同时最多显示的 Toast 数量（仅视觉）
wrapUpdate(fn: () => void) => void-包裹状态更新的函数（例如用于 view transitions）

方法

Method参数返回值描述
add(content: T, options?: ToastOptions)string将 Toast 加入队列，返回 Toast key
close(key: string)void按 key 关闭 Toast
pauseAll()void暂停所有 Toast 计时器
resumeAll()void恢复所有 Toast 计时器
clear()void关闭所有 Toast
subscribe(fn: () => void)() => void订阅队列变化，返回取消订阅函数

toast 函数

默认 toast 函数提供便捷方法用于显示 Toast：

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

// 基础 toast（默认约 4 秒后自动消失）
toast("Event has been created");

// 变体方法（默认同样约 4 秒后自动消失）
toast.success("File saved");
toast.info("New update available");
toast.warning("Please check your settings");
toast.danger("Something went wrong");

// 传入 options
toast("Event has been created", {
  description: "Your event has been scheduled for tomorrow",
  variant: "default",
  timeout: 5000, // 自定义超时：5 秒
  onClose: () => console.log("Closed"),
  actionProps: {
    children: "View",
    onPress: () => {},
  },
  indicator: <CustomIcon />,
});

// Promise 支持（自动显示加载指示）
toast.promise(
  uploadFile(),
  {
    loading: "Uploading file...",
    success: (data) => `File ${data.filename} uploaded`,
    error: "Failed to upload file",
  }
);

// 手动加载状态（持久 toast：不自动消失）
const loadingId = toast("Creating event...", {
  isLoading: true,
  timeout: 0, // 持久 toast：不自动消失
});

// 随后关闭并展示结果
toast.close(loadingId);
toast.success("Event created");

// 队列方法
toast.close(key);
toast.clear();
toast.pauseAll();
toast.resumeAll();

toast Options

Option类型默认值描述
titleReactNode-Toast 标题（变体方法的第一个参数）
descriptionReactNode-可选说明文本
variant"default" | "accent" | "success" | "warning" | "danger""default"视觉变体
indicatorReactNode-自定义指示图标（null 可隐藏）
actionPropsButtonProps-操作按钮 props
isLoadingbooleanfalse使用加载指示替代指示器
timeoutnumber4000自动消失超时（毫秒）。默认 4000ms（4 秒）。设为 0 表示持久 Toast，不自动消失
onClose() => void-Toast 关闭时的回调

toast.promise Options

Option类型默认值描述
loadingReactNode-Promise pending 时显示的消息
successReactNode | ((data: T) => ReactNode)-成功时显示的消息（可为函数）
errorReactNode | ((error: Error) => ReactNode)-失败时显示的消息（可为函数）

TimeField 时间字段

基于 React Aria TimeField 的时间输入字段，包含标签、说明与校验。

Toolbar 工具栏

用于承载可交互控件的容器，并支持方向键导航。

本页目录

引入设置用法简单 Toast变体自定义指示器Promise 与加载中回调放置位置自定义 Toast 渲染自定义队列组件结构样式传入 Tailwind CSS 类自定义组件类CSS 类基础类变体类交互状态API 参考Toast.Provider PropsToast PropsToast.Content PropsToast.Indicator PropsToast.Title PropsToast.Description PropsToast.ActionButton PropsToast.CloseButton PropsToastQueue构造选项方法toast 函数toast Optionstoast.promise Options