---
title: 所有版本
description: HeroUI v3 的所有更新与变更，包含新功能、修复以及破坏性变更。
---

<Callout type="info">
  **正在使用 AI 助手？** 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 [HeroUI MCP 服务器](/docs/ui-for-agents/mcp-server)。
</Callout>

## 最新版本

### v3.2.4

**2026 年 8 月 4 日**

补丁版本：[Autocomplete](/docs/components/autocomplete) 弹层不再裁剪末尾选项，`scroll="outside"` 的 [Modal](/docs/components/modal) 重新支持点击遮罩关闭，[Tabs](/docs/components/tabs) 的箭头滚动会精确停在边缘，`tailwind-variants` 升级到 `3.3.1` 以修复重新渲染后变体修饰符回退到错误类名的问题，React Aria 升级到 `1.20.0`（`react-aria@3.51.0`），并为 `@heroui/react` 添加了行为测试套件。

[阅读完整发布说明 →](/docs/react/releases/v3-2-4)

---

### v3.2.3

**2026 年 7 月 30 日**

补丁版本：[ComboBox](/docs/components/combo-box) 新增多选支持，样式采用逻辑 CSS 属性以更好地支持 RTL，`tailwind-variants` 升级到 `3.3.0`，并修复 `ScrollShadow`、`Spinner`、`InputOTP`、`Table` 以及 accent `Button` 焦点样式的问题。

[阅读完整发布说明 →](/docs/react/releases/v3-2-3)

---

### v3.2.2

**2026 年 6 月 19 日**

补丁版本：升级到 React Aria `1.19.0`（`react-aria@3.50.0`），为 `Tabs.ListContainer` 添加溢出滚动，修复清除/关闭按钮意外提交表单，以及 `Checkbox`、`Radio` 和 `Switch` 中视觉隐藏输入框导致的溢出滚动。

[阅读完整发布说明 →](/docs/react/releases/v3-2-2)

---

### v3.2.1

**2026 年 6 月 17 日**

补丁版本：`@heroui/react` 不再内置自己的 `react-aria` 副本。`react-aria` 的子路径在 Rollup 构建中被外部化，使消费方解析到项目中安装的单一 `react-aria`，而非内联副本。同时修复了 `SwitchGroup` 横向布局。

[阅读完整发布说明 →](/docs/react/releases/v3-2-1)

---

### v3.2.0

**2026 年 6 月 6 日**

基于 React Aria 1.18 的 Calendar 周/日视图、重做的年份选择器与范围日历演示，新增 Tooltip 延迟主题变量，并纳入随之发布的补丁修复。破坏性变更：`Radio`、`Checkbox`、`Switch` 改为显式的 `*.Content` 组合（控件嵌套进 `*.Content`，标签为纯文本、不嵌套 `<Label>`，帮助文本变为兄弟节点）。

[阅读完整发布说明 →](/docs/react/releases/v3-2-0)

---

### v3.1.0

**2026 年 5 月 25 日**

小版本发布：新增中文 React 文档与本地化示例，加入更可访问的 soft foreground 令牌和 vibrant palette 选项，统一滚动条系统，修复 `useTheme`、Toast、Fieldset、Link、浮层问题，并改进 Table、Picker 与 MenuItem 的 RTL 支持。

[阅读完整发布说明 →](/docs/react/releases/v3-1-0)

---

### v3.0.5

**2026 年 5 月 15 日**

补丁版本：`Text` 重命名为 `Typography` 以解决 `tailwind-merge` 冲突（⚠️ **破坏性变更**），派生颜色令牌重构为无前缀源变量，Checkbox 与 Radio 的 field-border 边框样式对齐，Calendar 悬停改用 `accent-soft-foreground` 以提升可读性，并新增 CLI 文档页。

[阅读完整发布说明 →](/docs/react/releases/v3-0-5)

---

### v3.0.4

**2026 年 5 月**

补丁版本：从 HeroUI Pro 移植的全新 `Text` 复合组件、文档主题选择器、在 45+ 个组件 CSS 文件中采用 `min()` 上限约束的圆角令牌、重做的 Table 聚焦环，以及对 Checkbox、Autocomplete、Tooltip 与表单字段内边距的修复。

<VideoPlayer
  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/heroui-oss-3.0.4-4k.mp4"
  muted
/>

[阅读完整发布说明 →](/docs/react/releases/v3-0-4)

---

### v3.0.3

**2026 年 4 月 17 日**

补丁版本：升级到 React Aria Components 1.17（合并依赖、安装更快、Table 支持可展开行），为 Vite 与 CRA 提供 `useTheme` Hook，为轻量级组件提供 DOM 多态的 render prop，并修复了 NumberField 的重置问题以及嵌套 Tabs 的样式问题。

[阅读完整发布说明 →](/docs/react/releases/v3-0-3)

---

### v3.0.2

**2026 年 4 月 3 日**

修复了多个 bug，Drawer 过渡更加平滑，新增了 `--backdrop` 主题变量，并优化了 trigger、arrow 与 Tag 的样式。修复了 Autocomplete 弹出层的宽度跟踪问题，浮层触发器现在使用 `inline-block`，Tag 在间距与无障碍方面也有所改进。

[阅读完整发布说明 →](/docs/react/releases/v3-0-2)

### v3.0.0

**2026 年 3 月**

<VideoPlayer
  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/videos/heroui-v3-release.mp4"
  height={430}
  muted
/>

面向 React 与 React Native 的彻底重写。包含 75+ Web 组件、37 个原生组件、Tailwind CSS v4、React Aria、复合组件架构、基于 OKLCH token 的 CSS 优先主题、通过 `data-reduce-motion` 控制动画，并面向利用 MCP Server、Agent Skills 与 LLMs.txt 的 AI 辅助开发而打造。

[阅读完整发布说明 →](/docs/react/releases/v3-0-0)

---

### HeroUI Pro

<DocsImage
  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-pro@2x.jpg"
  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/heroui-pro-dark@2x.jpg"
  alt="HeroUI Pro"
  href="https://heroui.pro"
/>

面向 React 与 React Native 的高级组件、模板与 AI 工具。预售价格现已上线。

[访问 heroui.pro 查看套餐与定价 →](https://heroui.pro)

---

### v3.0.0-rc.1

**2026 年 3 月 14 日**

<DocsImage
  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/rc-1-light@2x.jpg"
  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/rc-1-dark@2x.jpg"
  alt="HeroUI v3 RC 1"
  href="/docs/react/releases/v3-0-0-rc-1"
/>

新增七个组件（[Drawer](/docs/components/drawer)、[ToggleButton](/docs/components/toggle-button)、[ToggleButtonGroup](/docs/components/toggle-button-group)、[Meter](/docs/components/meter)、[ProgressBar](/docs/components/progress-bar)、[ProgressCircle](/docs/components/progress-circle)、[Toolbar](/docs/components/toolbar)），为 [Table](/docs/components/table) 和 [ListBox](/docs/components/list-box) 引入了 **虚拟化**，[ButtonGroup](/docs/components/button-group) 新增 `ButtonGroup.Separator` 与垂直方向支持，React Aria Components 升级到 v1.16.0。

[阅读完整发布说明 →](/docs/react/releases/v3-0-0-rc-1)

---

### v3.0.0-beta.8

**2026 年 3 月 2 日**

<DocsImage
  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-8-light@2x.jpg"
  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-8-dark@2x.jpg"
  alt="HeroUI v3 Beta 8"
  href="/docs/react/releases/v3-0-0-beta-8"
/>

此版本新增三个组件（[Badge](/docs/components/badge)、[Pagination](/docs/components/pagination)、[Table](/docs/components/table)），并为 [DateField](/docs/components/date-field) 与 [TimeField](/docs/components/time-field) 提供了新的 `InputContainer` 组合 API。⚠️ **破坏性变更**：TextField 的 CSS 类已从 `.text-field` 重命名为 `.textfield`。

[阅读完整发布说明 →](/docs/react/releases/v3-0-0-beta-8)

---

### v3.0.0-beta.7

**2026 年 2 月 18 日**

<DocsImage
  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-7-light@2x.jpg"
  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-7-dark@2x.jpg"
  alt="HeroUI v3 Beta 7"
  href="/docs/react/releases/v3-0-0-beta-7"
/>

此版本引入了完整的**日期与时间**系统，包含四个新组件（[Calendar](/docs/components/calendar)、[RangeCalendar](/docs/components/range-calendar)、[DatePicker](/docs/components/date-picker)、[DateRangePicker](/docs/components/date-range-picker)），新增了 [Switch.Content](/docs/components/switch) 子组件、显式的 [Tabs.Separator](/docs/components/tabs) 用于按需启用分隔线，以及 ⚠️ **破坏性变更**：从 Tabs 中移除 `hideSeparator`，并将 `DateInputGroup` / `ColorInputGroup` 合并到各自的 Field 组件之下。

[阅读完整发布说明 →](/docs/react/releases/v3-0-0-beta-7)

---

### v3.0.0-beta.6

**2026 年 2 月 6 日**

<DocsImage
  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-6-light@2x.jpg"
  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-6-dark@2x.jpg"
  alt="HeroUI v3 Beta 6"
  href="/docs/react/releases/v3-0-0-beta-6"
/>

此版本引入了完整的**颜色系统**，包含六个新组件（[ColorPicker](/docs/components/color-picker)、[ColorArea](/docs/components/color-area)、[ColorSlider](/docs/components/color-slider)、[ColorField](/docs/components/color-field)、[ColorSwatch](/docs/components/color-swatch)、[ColorSwatchPicker](/docs/components/color-swatch-picker)），对 [Toast](/docs/components/toast) 进行了重大改进，加入了加载状态与 Promise 支持，[Separator](/docs/components/separator) 新增变体，以及 ⚠️ **破坏性变更**：将 `Toast.Container` 重命名为 `Toast.Provider`，并将 CSS 类名统一为连字符格式。

[阅读完整发布说明 →](/docs/react/releases/v3-0-0-beta-6)

---
### v3.0.0-beta.5

- 修复构建问题

### v3.0.0-beta.4

**2026 年 1 月 20 日**

<DocsImage
  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-4-light@2x.jpg"
  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-4-dark@2x.jpg"
  alt="HeroUI v3 Beta 4"
  href="/docs/react/releases/v3-0-0-beta-4"
/>

<Callout type="warning">
  **已修复关键构建问题**：此版本（beta.4）存在一个关键构建问题，已在 **beta.5** 中修复。请升级到 `@heroui/styles@3.0.0-beta.5` 与 `@heroui/react@3.0.0-beta.5`，以确保 TypeScript 声明文件能正确生成、导出能正确解析。
</Callout>

此版本引入了用于可视化主题定制的全新[主题构建器](/themes)、三个新组件（[Autocomplete](/docs/components/autocomplete)、[Breadcrumbs](/docs/components/breadcrumbs)、[Toast](/docs/components/toast)），为 [Tabs](/docs/components/tabs) 添加了 secondary 变体，为 [Input](/docs/components/input) 与 [InputGroup](/docs/components/input-group) 添加了 primary / secondary 变体，以及 ⚠️ **破坏性变更**：移除了 Link 的下划线变体，并从表单组件中移除了 `isInSurface` prop。

[阅读完整发布说明 →](/docs/react/releases/v3-0-0-beta-4)

---

### v3.0.0-beta.3

**2025 年 12 月 19 日**

<DocsImage
  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-3-light@2x.jpg"
  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-3-dark@2x.jpg"
  alt="HeroUI v3 Beta 3"
  href="/docs/react/releases/v3-0-0-beta-3"
/>


此版本引入了七个新组件（[ButtonGroup](/docs/components/button-group)、[DateField](/docs/components/date-field)、[ErrorMessage](/docs/components/error-message)、[ScrollShadow](/docs/components/scroll-shadow)、[SearchField](/docs/components/search-field)、[TagGroup](/docs/components/tag-group)、[TimeField](/docs/components/time-field)），为表单与输入组件添加了 `fullWidth` 支持，为 [Tabs](/docs/components/tabs)、[ButtonGroup](/docs/components/button-group) 和 [Accordion](/docs/components/accordion) 引入 `hideSeparator` 以获得更简洁的布局，包含若干样式修复，以及 ⚠️ **破坏性变更**：移除 `asChild` prop，并更新了 [AlertDialog](/docs/components/alert-dialog) 与 [Modal](/docs/components/modal) 的 backdrop 变体。

[阅读完整发布说明 →](/docs/react/releases/v3-0-0-beta-3)

---

### v3.0.0-beta.2

**2025 年 11 月 20 日**

<DocsImage
  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-2-light@2x.jpg"
  darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/beta-2-dark@2x.jpg"
  alt="HeroUI v3 Beta 2"
  href="/docs/react/releases/v3-0-0-beta-2"
/>


此版本引入了六个重要的新组件（[AlertDialog](/docs/components/alert-dialog)、[ComboBox](/docs/components/combo-box)、[Dropdown](/docs/components/dropdown)、[InputGroup](/docs/components/input-group)、[Modal](/docs/components/modal)、[NumberField](/docs/components/number-field)），增强了主题兼容性与动效偏好支持，改进了 [Select](/docs/components/select) 组件的 API（包含 ⚠️ **破坏性变更**），并附带多项优化和 bug 修复。

[阅读完整发布说明 →](/docs/react/releases/v3-0-0-beta-2)

---

### v3.0.0-beta.1

**2025 年 11 月 6 日**

<VideoPlayer
  src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/videos/v3-beta-1.mp4"
  poster="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/videos/v3-beta-1-poster.png"
  height={430}
  muted
/>

此版本对 HeroUI v3 进行了全面重新设计，将 v2 的美观与动效与 v3 的简洁性融为一体。所有组件均经过重新设计，新增 8 个组件（[Alert](/docs/components/alert)、[Checkbox](/docs/components/checkbox)、[InputOTP](/docs/components/input-otp)、[ListBox](/docs/components/list-box)、[Select](/docs/components/select)、[Slider](/docs/components/slider)、[Surface](/docs/components/surface)），并对设计系统进行了彻底重构，包括更完善的颜色 token、阴影体系与整体架构。本版本还包含对设计系统变量、组件 API 以及灵活组件模式的破坏性变更。

[阅读完整发布说明 →](/docs/react/releases/v3-0-0-beta-1)

---

## 早期版本

### v3.0.0-alpha.35

**2025 年 10 月 21 日**

#### React Server Components 支持
- 修复了复合组件在 React Server Components（RSC）中无法正常工作的关键问题
- 将复合组件模式的逻辑从组件移至 index 文件，解决 `"use client"` 冲突
- **（⚠️ 破坏性变更）**：主组件现在需要 `.Root` 后缀（例如 `<Avatar>` → `<Avatar.Root>`）
- 命名导出保持不变，并完全继续支持

#### React 19 相关改进
- 移除了 `forwardRef`（[React 19](https://react.dev/blog/2024/12/05/react-19#ref-as-a-prop) 现已原生支持）
- 简化了 Context 的使用方式（`Context.Provider` → [React 19](https://react.dev/blog/2024/12/05/react-19#context-as-a-provider)）

#### Switch 组件重构
- **（⚠️ 破坏性变更）**：将 Switch 与 SwitchGroup 拆分为独立组件
- 更简洁的 API：`<SwitchGroup>` 取代 `<Switch.Group>` 和 `<Switch.GroupItems>`
- 与 Radio / RadioGroup 模式保持一致
- 各自拥有独立的样式、类型和实现

#### 受影响的组件
以下复合组件均需要使用 `.Root` 后缀：`Accordion`、`Avatar`、`Card`、`Disclosure`、`Fieldset`、`Kbd`、`Link`、`Popover`、`Radio`、`Switch`、`Tabs`、`Tooltip`

[阅读完整发布说明 →](/docs/react/releases/v3-0-0-alpha-35)

### v3.0.0-alpha.34

**2025 年 10 月 15 日**

- 新增基于表单的组件：[Description](/docs/components/description)、[FieldError](/docs/components/field-error)、[Fieldset](/docs/components/fieldset)、[Form](/docs/components/form)、[Input](/docs/components/input)、[Label](/docs/components/label)、[RadioGroup](/docs/components/radio-group)、[TextField](/docs/components/text-field) 以及 [TextArea](/docs/components/textarea)
- 引入表单字段相关的 token `--field-*`
- 按类别重新组织 Storybook
- **（破坏性变更）**：在 [Skeleton](/docs/components/skeleton) 中将 `--skeleton-default-animation-type` 重命名为 `--skeleton-animation`
- 统一了各组件中 `data-slot` 标记的命名
- 改进了文档


[阅读完整发布说明 →](/docs/react/releases/v3-0-0-alpha-34)

### v3.0.0-alpha.33

**2025 年 10 月 5 日**

- 将 RAC 升级至 [2025 年 10 月 2 日发布的版本](https://react-spectrum.adobe.com/releases/2025-10-02.html)
- 调整了 [Tabs](/docs/components/tabs) 中 Indicator 的顺序（**破坏性变更**）
- 将 [Tabs](/docs/components/tabs) 组件改为使用 React Aria 的 `SelectionIndicator`，现已支持 SSR
- 更新了 [Disclosure](/docs/components/disclosure) 和 [Disclosure Group](/docs/components/disclosure-group) 组件，使其在展开/折叠动画中使用 RAC 的 CSS 变量
- 更新了 [Switch](/docs/components/switch) 组件的样式与动画
- 为 [Switch](/docs/components/switch#sizes) 新增 `size` 变体并补充了对应演示
- 在 [Button](/docs/components/button)、[Tabs](/docs/components/tabs)、[Disclosure](/docs/components/disclosure)、[Disclosure Group](/docs/components/disclosure-group) 中添加了相关示例
- 改进了文档


[阅读完整发布说明 →](/docs/react/releases/v3-0-0-alpha-33)

### v3.0.0-alpha.32

**2025 年 10 月 1 日**

重新设计了 Card 组件，引入了[新变体](/docs/components/card)，新增了 [CloseButton](/docs/components/close-button) 组件，发布了面向 AI 编码助手的 [MCP 服务器](/docs/ui-for-agents/mcp-server)，并改进了文档。

[阅读完整发布说明 →](/docs/react/releases/v3-0-0-alpha-32)

### v3.0.0-alpha.31

**2025 年 9 月 22 日**

- 🎨 **展示页面** - 使用 HeroUI 构建的站点案例集
- 🌀 **DisclosureGroup 组件** - 将多个 Disclosure 组合在一起
- 📇 **Card 组件**（预览） - Card 组件的首个版本
- 🔀 **Switch 组件**（预览） - 用于设置项的切换开关

---

## 发布周期

HeroUI v3 现已稳定。后续版本将遵循固定的发布周期：

- **补丁版本**：按需修复 bug 与小幅优化
- **次要版本**：新增组件与功能，通常每月一次
- **主版本**：包含架构层面的变更，并提供迁移指南

## 参与贡献

发现问题或希望参与贡献？欢迎查看我们的 [GitHub 仓库](https://github.com/heroui-inc/heroui)。
