用法

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

组件结构

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

export default () => (
  <Tooltip>
    <Tooltip.Trigger>
      <Button>Hover for tooltip</Button>
    </Tooltip.Trigger>
    <Tooltip.Content>
      <Tooltip.Arrow />
      关于此元素的有用信息
    </Tooltip.Content>
  </Tooltip>
)

示例

位置

悬停按钮

带箭头

自定义触发

活跃

渲染函数

自定义样式

Tailwind CSS

全局 CSS

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

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

  .tooltip__trigger {
    @apply cursor-help;
  }
}

样式参考

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

全局延迟配置

你可以通过定义 CSS 变量，为应用中所有 Tooltip 设置默认的显示与隐藏延迟：

/* 在你的全局 CSS 文件中 */
:root {
  --tooltip-delay: 1500ms;
  --tooltip-close-delay: 500ms;
}

/* 也可以为浅色/深色主题设置不同的值 */
.light, [data-theme="light"] {
  --tooltip-delay: 1200ms;
}

.dark, [data-theme="dark"] {
  --tooltip-close-delay: 300ms;
}

值支持 ms、s 等 CSS 时间单位。在单个 Tooltip 上指定 delay 或 closeDelay 时，会覆盖这些全局设置。

CSS 类

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

基础类

.tooltip - 带动画的基础 Tooltip 样式
.tooltip__trigger - 触发元素样式

交互状态

组件支持以下动画相关状态：

进入：[data-entering] — Tooltip 出现过程中应用
离开：[data-exiting] — Tooltip 消失过程中应用
位置：[data-placement="*"] — 根据 Tooltip 位置应用

API 参考

Prop	类型	默认值	描述
`children`	`React.ReactNode`	-	触发元素与内容
`delay`	`number`	`1500` 或 CSS 变量	显示 Tooltip 前的延迟（毫秒）；可通过 `--tooltip-delay` CSS 变量全局配置
`closeDelay`	`number`	`500` 或 CSS 变量	隐藏 Tooltip 前的延迟（毫秒）；可通过 `--tooltip-close-delay` CSS 变量全局配置
`trigger`	`"hover" \| "focus"`	`"hover"`	Tooltip 的触发方式
`isDisabled`	`boolean`	`false`	是否禁用 Tooltip
`shouldSkipAnimation`	`boolean`	`false`	在多个 Tooltip 之间快速切换时，是否跳过进入与退出动画

Tooltip.Content

Prop	类型	默认值	描述
`children`	`React.ReactNode`	-	在 Tooltip 中展示的内容
`showArrow`	`boolean`	`false`	是否显示箭头指示器
`offset`	`number`	`3`（带箭头时为 7）	与触发元素的距离
`placement`	`"top" \| "bottom" \| "left" \| "right"` (及变体)	`"top"`	Tooltip 的位置
`className`	`string`	-	额外的 CSS 类名
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, TooltipRenderProps>`	-	通过自定义渲染函数覆盖默认的 DOM 元素。

Tooltip.Trigger

Prop	类型	默认值	描述
`children`	`React.ReactNode`	-	触发 Tooltip 的元素
`className`	`string`	-	额外的 CSS 类名

Tooltip.Arrow

Prop	类型	默认值	描述
`children`	`React.ReactNode`	-	自定义箭头元素
`className`	`string`	-	额外的 CSS 类名
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, OverlayArrowRenderProps>`	-	通过自定义渲染函数覆盖默认的 DOM 元素。

Tooltip 工具提示更新

用法