v3.0.2

2026 年 4 月 3 日

补丁版本，包含若干 bug 修复、样式优化，以及新增的 --backdrop 主题变量。Drawer 过渡已重写为原生 CSS，动画更加平滑。浮层触发器现在以 inline-block 形式呈现，Tooltip 和 Popover 的默认箭头形状也已更新。

安装

升级到最新版本：

npm

```bash
npm i @heroui/styles@latest @heroui/react@latest
```

pnpm

```bash
pnpm add @heroui/styles@latest @heroui/react@latest
```

yarn

```bash
yarn add @heroui/styles@latest @heroui/react@latest
```

bun

```bash
bun add @heroui/styles@latest @heroui/react@latest
```

正在使用 AI 助手？ 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 HeroUI MCP 服务器。

新增功能

--backdrop 主题变量

新增用于浮层背景遮罩的 --backdrop CSS 变量（#6375）。浅色主题默认值为 rgba(0, 0, 0, 0.5)，深色主题为 rgba(0, 0, 0, 0.6)。Modal、AlertDialog 与 Drawer 现在都引用该变量，而不再使用硬编码的值。

可以在全局进行覆写：

:root {
  --backdrop: rgba(0, 0, 0, 0.7);
}

也可以直接使用对应的工具类 bg-backdrop。

样式改进

Trigger 改用 inline-block 显示

Popover、Tooltip、Dropdown、Modal、AlertDialog、Drawer 与 Disclosure 中的触发元素现在都会应用 inline-block，避免触发器包裹行内内容时出现布局塌陷的问题（#6373）。

Tooltip 与 Popover 的箭头

默认箭头的 SVG 路径已从二次贝塞尔曲线改为三次贝塞尔曲线，形状更平滑、更自然（#6372）。

Tag 的间距

为提升可读性，Tag 在 sm（由 px-1 改为 px-2）和 md（由 px-1.5 改为 px-2）尺寸下增加了水平内边距（#6315）。

Bug 修复

• Autocomplete：popover 上的 --trigger-width CSS 变量现在通过 useResizeObserver 跟踪触发元素的宽度，修复了下拉宽度不对齐的问题（#6374）
• Drawer：面板过渡已从 Tailwind 的 animate-in / animate-out 重写为原生的 CSS translate 过渡，使各种放置位置下的开关动画都更加平滑（#6393）
• InputGroup：secondary 变体的聚焦背景现在仅在实际的 input 或 textarea 获得焦点时才会触发，不再因组内任意可聚焦的子元素被聚焦而触发（#6362）
• Tag：Tag 内部的 CloseButton 现在带有显式的 aria-label="Remove tag"，可被屏幕阅读器正确识别（#6341）

链接

• 组件文档
• Figma Kit v3
• GitHub 仓库
• GitHub PR #6364

贡献者

感谢每一位为本次发布做出贡献的开发者！