所有版本
HeroUI v3 的所有更新与变更，包含新功能、修复以及破坏性变更。
正在使用 AI 助手？ 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 HeroUI MCP 服务器。
最新版本
v3.1.0
2026 年 5 月 25 日
小版本发布：新增中文 React 文档与本地化示例，加入更可访问的 soft foreground 令牌和 vibrant palette 选项，统一滚动条系统，修复 useTheme、Toast、Fieldset、Link、浮层问题，并改进 Table、Picker 与 MenuItem 的 RTL 支持。
v3.0.5
2026 年 5 月 15 日
补丁版本：Text 重命名为 Typography 以解决 tailwind-merge 冲突（⚠️ 破坏性变更），派生颜色令牌重构为无前缀源变量，Checkbox 与 Radio 的 field-border 边框样式对齐，Calendar 悬停改用 accent-soft-foreground 以提升可读性，并新增 CLI 文档页。
v3.0.4
2026 年 5 月
补丁版本：从 HeroUI Pro 移植的全新 Text 复合组件、文档主题选择器、在 45+ 个组件 CSS 文件中采用 min() 上限约束的圆角令牌、重做的 Table 聚焦环，以及对 Checkbox、Autocomplete、Tooltip 与表单字段内边距的修复。
v3.0.3
2026 年 4 月 17 日
补丁版本：升级到 React Aria Components 1.17（合并依赖、安装更快、Table 支持可展开行），为 Vite 与 CRA 提供 useTheme Hook，为轻量级组件提供 DOM 多态的 render prop，并修复了 NumberField 的重置问题以及嵌套 Tabs 的样式问题。
v3.0.2
2026 年 4 月 3 日
修复了多个 bug，Drawer 过渡更加平滑，新增了 --backdrop 主题变量，并优化了 trigger、arrow 与 Tag 的样式。修复了 Autocomplete 弹出层的宽度跟踪问题，浮层触发器现在使用 inline-block，Tag 在间距与无障碍方面也有所改进。
v3.0.0
2026 年 3 月
面向 React 与 React Native 的彻底重写。包含 75+ Web 组件、37 个原生组件、Tailwind CSS v4、React Aria、复合组件架构、基于 OKLCH token 的 CSS 优先主题、通过 data-reduce-motion 控制动画，并面向利用 MCP Server、Agent Skills 与 LLMs.txt 的 AI 辅助开发而打造。
HeroUI Pro
面向 React 与 React Native 的高级组件、模板与 AI 工具。预售价格现已上线。
v3.0.0-rc.1
2026 年 3 月 14 日
新增七个组件（Drawer、ToggleButton、ToggleButtonGroup、Meter、ProgressBar、ProgressCircle、Toolbar），为 Table 和 ListBox 引入了 虚拟化，ButtonGroup 新增 ButtonGroup.Separator 与垂直方向支持，React Aria Components 升级到 v1.16.0。
v3.0.0-beta.8
2026 年 3 月 2 日
此版本新增三个组件（Badge、Pagination、Table），并为 DateField 与 TimeField 提供了新的 InputContainer 组合 API。⚠️ 破坏性变更：TextField 的 CSS 类已从 .text-field 重命名为 .textfield。
v3.0.0-beta.7
2026 年 2 月 18 日
此版本引入了完整的日期与时间系统，包含四个新组件（Calendar、RangeCalendar、DatePicker、DateRangePicker），新增了 Switch.Content 子组件、显式的 Tabs.Separator 用于按需启用分隔线，以及 ⚠️ 破坏性变更：从 Tabs 中移除 hideSeparator，并将 DateInputGroup / ColorInputGroup 合并到各自的 Field 组件之下。
v3.0.0-beta.6
2026 年 2 月 6 日
此版本引入了完整的颜色系统，包含六个新组件（ColorPicker、ColorArea、ColorSlider、ColorField、ColorSwatch、ColorSwatchPicker），对 Toast 进行了重大改进，加入了加载状态与 Promise 支持，Separator 新增变体，以及 ⚠️ 破坏性变更：将 Toast.Container 重命名为 Toast.Provider，并将 CSS 类名统一为连字符格式。
v3.0.0-beta.5
- 修复构建问题
v3.0.0-beta.4
2026 年 1 月 20 日
已修复关键构建问题：此版本（beta.4）存在一个关键构建问题，已在 beta.5 中修复。请升级到 @heroui/styles@3.0.0-beta.5 与 @heroui/react@3.0.0-beta.5，以确保 TypeScript 声明文件能正确生成、导出能正确解析。
此版本引入了用于可视化主题定制的全新主题构建器、三个新组件（Autocomplete、Breadcrumbs、Toast），为 Tabs 添加了 secondary 变体，为 Input 与 InputGroup 添加了 primary / secondary 变体，以及 ⚠️ 破坏性变更：移除了 Link 的下划线变体，并从表单组件中移除了 isInSurface prop。
v3.0.0-beta.3
2025 年 12 月 19 日
此版本引入了七个新组件（ButtonGroup、DateField、ErrorMessage、ScrollShadow、SearchField、TagGroup、TimeField），为表单与输入组件添加了 fullWidth 支持，为 Tabs、ButtonGroup 和 Accordion 引入 hideSeparator 以获得更简洁的布局，包含若干样式修复，以及 ⚠️ 破坏性变更：移除 asChild prop，并更新了 AlertDialog 与 Modal 的 backdrop 变体。
v3.0.0-beta.2
2025 年 11 月 20 日
此版本引入了六个重要的新组件（AlertDialog、ComboBox、Dropdown、InputGroup、Modal、NumberField），增强了主题兼容性与动效偏好支持，改进了 Select 组件的 API（包含 ⚠️ 破坏性变更），并附带多项优化和 bug 修复。
v3.0.0-beta.1
2025 年 11 月 6 日
此版本对 HeroUI v3 进行了全面重新设计，将 v2 的美观与动效与 v3 的简洁性融为一体。所有组件均经过重新设计，新增 8 个组件（Alert、Checkbox、InputOTP、ListBox、Select、Slider、Surface），并对设计系统进行了彻底重构，包括更完善的颜色 token、阴影体系与整体架构。本版本还包含对设计系统变量、组件 API 以及灵活组件模式的破坏性变更。
早期版本
v3.0.0-alpha.35
2025 年 10 月 21 日
React Server Components 支持
- 修复了复合组件在 React Server Components（RSC）中无法正常工作的关键问题
- 将复合组件模式的逻辑从组件移至 index 文件，解决
"use client"冲突 - （⚠️ 破坏性变更）：主组件现在需要
.Root后缀（例如<Avatar>→<Avatar.Root>） - 命名导出保持不变，并完全继续支持
React 19 相关改进
Switch 组件重构
- （⚠️ 破坏性变更）：将 Switch 与 SwitchGroup 拆分为独立组件
- 更简洁的 API：
<SwitchGroup>取代<Switch.Group>和<Switch.GroupItems> - 与 Radio / RadioGroup 模式保持一致
- 各自拥有独立的样式、类型和实现
受影响的组件
以下复合组件均需要使用 .Root 后缀：Accordion、Avatar、Card、Disclosure、Fieldset、Kbd、Link、Popover、Radio、Switch、Tabs、Tooltip
v3.0.0-alpha.34
2025 年 10 月 15 日
- 新增基于表单的组件：Description、FieldError、Fieldset、Form、Input、Label、RadioGroup、TextField 以及 TextArea
- 引入表单字段相关的 token
--field-* - 按类别重新组织 Storybook
- （破坏性变更）：在 Skeleton 中将
--skeleton-default-animation-type重命名为--skeleton-animation - 统一了各组件中
data-slot标记的命名 - 改进了文档
v3.0.0-alpha.33
2025 年 10 月 5 日
- 将 RAC 升级至 2025 年 10 月 2 日发布的版本
- 调整了 Tabs 中 Indicator 的顺序（破坏性变更）
- 将 Tabs 组件改为使用 React Aria 的
SelectionIndicator，现已支持 SSR - 更新了 Disclosure 和 Disclosure Group 组件，使其在展开/折叠动画中使用 RAC 的 CSS 变量
- 更新了 Switch 组件的样式与动画
- 为 Switch 新增
size变体并补充了对应演示 - 在 Button、Tabs、Disclosure、Disclosure Group 中添加了相关示例
- 改进了文档
v3.0.0-alpha.32
2025 年 10 月 1 日
重新设计了 Card 组件，引入了新变体，新增了 CloseButton 组件，发布了面向 AI 编码助手的 MCP 服务器，并改进了文档。
v3.0.0-alpha.31
2025 年 9 月 22 日
- 🎨 展示页面 - 使用 HeroUI 构建的站点案例集
- 🌀 DisclosureGroup 组件 - 将多个 Disclosure 组合在一起
- 📇 Card 组件（预览） - Card 组件的首个版本
- 🔀 Switch 组件（预览） - 用于设置项的切换开关
发布周期
HeroUI v3 现已稳定。后续版本将遵循固定的发布周期：
- 补丁版本：按需修复 bug 与小幅优化
- 次要版本：新增组件与功能，通常每月一次
- 主版本：包含架构层面的变更，并提供迁移指南
参与贡献
发现问题或希望参与贡献？欢迎查看我们的 GitHub 仓库。