apps/docs/content/docs/cn/react/releases/index.mdx
2026 年 8 月 4 日
补丁版本：Autocomplete 弹层不再裁剪末尾选项，scroll="outside" 的 Modal 重新支持点击遮罩关闭，Tabs 的箭头滚动会精确停在边缘，tailwind-variants 升级到 3.3.1 以修复重新渲染后变体修饰符回退到错误类名的问题，React Aria 升级到 1.20.0（[email protected]），并为 @heroui/react 添加了行为测试套件。
2026 年 7 月 30 日
补丁版本：ComboBox 新增多选支持，样式采用逻辑 CSS 属性以更好地支持 RTL，tailwind-variants 升级到 3.3.0，并修复 ScrollShadow、Spinner、InputOTP、Table 以及 accent Button 焦点样式的问题。
2026 年 6 月 19 日
补丁版本：升级到 React Aria 1.19.0（[email protected]），为 Tabs.ListContainer 添加溢出滚动，修复清除/关闭按钮意外提交表单，以及 Checkbox、Radio 和 Switch 中视觉隐藏输入框导致的溢出滚动。
2026 年 6 月 17 日
补丁版本：@heroui/react 不再内置自己的 react-aria 副本。react-aria 的子路径在 Rollup 构建中被外部化，使消费方解析到项目中安装的单一 react-aria，而非内联副本。同时修复了 SwitchGroup 横向布局。
2026 年 6 月 6 日
基于 React Aria 1.18 的 Calendar 周/日视图、重做的年份选择器与范围日历演示，新增 Tooltip 延迟主题变量，并纳入随之发布的补丁修复。破坏性变更：Radio、Checkbox、Switch 改为显式的 *.Content 组合（控件嵌套进 *.Content，标签为纯文本、不嵌套 <Label>，帮助文本变为兄弟节点）。
2026 年 5 月 25 日
小版本发布：新增中文 React 文档与本地化示例，加入更可访问的 soft foreground 令牌和 vibrant palette 选项，统一滚动条系统，修复 useTheme、Toast、Fieldset、Link、浮层问题，并改进 Table、Picker 与 MenuItem 的 RTL 支持。
2026 年 5 月 15 日
补丁版本：Text 重命名为 Typography 以解决 tailwind-merge 冲突（⚠️ 破坏性变更），派生颜色令牌重构为无前缀源变量，Checkbox 与 Radio 的 field-border 边框样式对齐，Calendar 悬停改用 accent-soft-foreground 以提升可读性，并新增 CLI 文档页。
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 />
2026 年 4 月 17 日
补丁版本：升级到 React Aria Components 1.17（合并依赖、安装更快、Table 支持可展开行），为 Vite 与 CRA 提供 useTheme Hook，为轻量级组件提供 DOM 多态的 render prop，并修复了 NumberField 的重置问题以及嵌套 Tabs 的样式问题。
2026 年 4 月 3 日
修复了多个 bug，Drawer 过渡更加平滑，新增了 --backdrop 主题变量，并优化了 trigger、arrow 与 Tag 的样式。修复了 Autocomplete 弹出层的宽度跟踪问题，浮层触发器现在使用 inline-block，Tag 在间距与无障碍方面也有所改进。
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 辅助开发而打造。
<DocsImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/[email protected]" darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/[email protected]" alt="HeroUI Pro" href="https://heroui.pro" />
面向 React 与 React Native 的高级组件、模板与 AI 工具。预售价格现已上线。
2026 年 3 月 14 日
<DocsImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/[email protected]" darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/[email protected]" alt="HeroUI v3 RC 1" href="/docs/react/releases/v3-0-0-rc-1" />
新增七个组件（Drawer、ToggleButton、ToggleButtonGroup、Meter、ProgressBar、ProgressCircle、Toolbar），为 Table 和 ListBox 引入了 虚拟化，ButtonGroup 新增 ButtonGroup.Separator 与垂直方向支持，React Aria Components 升级到 v1.16.0。
2026 年 3 月 2 日
<DocsImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/[email protected]" darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/[email protected]" alt="HeroUI v3 Beta 8" href="/docs/react/releases/v3-0-0-beta-8" />
此版本新增三个组件（Badge、Pagination、Table），并为 DateField 与 TimeField 提供了新的 InputContainer 组合 API。⚠️ 破坏性变更：TextField 的 CSS 类已从 .text-field 重命名为 .textfield。
2026 年 2 月 18 日
<DocsImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/[email protected]" darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/[email protected]" alt="HeroUI v3 Beta 7" href="/docs/react/releases/v3-0-0-beta-7" />
此版本引入了完整的日期与时间系统，包含四个新组件（Calendar、RangeCalendar、DatePicker、DateRangePicker），新增了 Switch.Content 子组件、显式的 Tabs.Separator 用于按需启用分隔线，以及 ⚠️ 破坏性变更：从 Tabs 中移除 hideSeparator，并将 DateInputGroup / ColorInputGroup 合并到各自的 Field 组件之下。
2026 年 2 月 6 日
<DocsImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/[email protected]" darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/[email protected]" alt="HeroUI v3 Beta 6" href="/docs/react/releases/v3-0-0-beta-6" />
此版本引入了完整的颜色系统，包含六个新组件（ColorPicker、ColorArea、ColorSlider、ColorField、ColorSwatch、ColorSwatchPicker），对 Toast 进行了重大改进，加入了加载状态与 Promise 支持，Separator 新增变体，以及 ⚠️ 破坏性变更：将 Toast.Container 重命名为 Toast.Provider，并将 CSS 类名统一为连字符格式。
2026 年 1 月 20 日
<DocsImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/[email protected]" darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/[email protected]" alt="HeroUI v3 Beta 4" href="/docs/react/releases/v3-0-0-beta-4" />
<Callout type="warning"> **已修复关键构建问题**：此版本（beta.4）存在一个关键构建问题，已在 **beta.5** 中修复。请升级到 `@heroui/[email protected]` 与 `@heroui/[email protected]`，以确保 TypeScript 声明文件能正确生成、导出能正确解析。 </Callout>此版本引入了用于可视化主题定制的全新主题构建器、三个新组件（Autocomplete、Breadcrumbs、Toast），为 Tabs 添加了 secondary 变体，为 Input 与 InputGroup 添加了 primary / secondary 变体，以及 ⚠️ 破坏性变更：移除了 Link 的下划线变体，并从表单组件中移除了 isInSurface prop。
2025 年 12 月 19 日
<DocsImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/[email protected]" darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/[email protected]" alt="HeroUI v3 Beta 3" href="/docs/react/releases/v3-0-0-beta-3" />
此版本引入了七个新组件（ButtonGroup、DateField、ErrorMessage、ScrollShadow、SearchField、TagGroup、TimeField），为表单与输入组件添加了 fullWidth 支持，为 Tabs、ButtonGroup 和 Accordion 引入 hideSeparator 以获得更简洁的布局，包含若干样式修复，以及 ⚠️ 破坏性变更：移除 asChild prop，并更新了 AlertDialog 与 Modal 的 backdrop 变体。
2025 年 11 月 20 日
<DocsImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/[email protected]" darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/versions/[email protected]" alt="HeroUI v3 Beta 2" href="/docs/react/releases/v3-0-0-beta-2" />
此版本引入了六个重要的新组件（AlertDialog、ComboBox、Dropdown、InputGroup、Modal、NumberField），增强了主题兼容性与动效偏好支持，改进了 Select 组件的 API（包含 ⚠️ 破坏性变更），并附带多项优化和 bug 修复。
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、Checkbox、InputOTP、ListBox、Select、Slider、Surface），并对设计系统进行了彻底重构，包括更完善的颜色 token、阴影体系与整体架构。本版本还包含对设计系统变量、组件 API 以及灵活组件模式的破坏性变更。
2025 年 10 月 21 日
"use client" 冲突.Root 后缀（例如 <Avatar> → <Avatar.Root>）<SwitchGroup> 取代 <Switch.Group> 和 <Switch.GroupItems>以下复合组件均需要使用 .Root 后缀：Accordion、Avatar、Card、Disclosure、Fieldset、Kbd、Link、Popover、Radio、Switch、Tabs、Tooltip
2025 年 10 月 15 日
--field-*--skeleton-default-animation-type 重命名为 --skeleton-animationdata-slot 标记的命名2025 年 10 月 5 日
SelectionIndicator，现已支持 SSRsize 变体并补充了对应演示2025 年 10 月 1 日
重新设计了 Card 组件，引入了新变体，新增了 CloseButton 组件，发布了面向 AI 编码助手的 MCP 服务器，并改进了文档。
2025 年 9 月 22 日
HeroUI v3 现已稳定。后续版本将遵循固定的发布周期：
发现问题或希望参与贡献？欢迎查看我们的 GitHub 仓库。