2025 年 12 月 19 日

此版本引入了七个新组件（ButtonGroup、DateField、ErrorMessage、ScrollShadow、SearchField、TagGroup、TimeField），为表单组件添加 fullWidth 支持，为 Tabs、ButtonGroup 与 Accordion 引入 hideSeparator，包含若干样式修复，以及 ⚠️ 破坏性变更：移除 asChild prop，并更新了 AlertDialog 与 Modal 的 backdrop 变体。

安装

升级到最新版本：

npm i @heroui/styles@beta @heroui/react@beta

pnpm add @heroui/styles@beta @heroui/react@beta

yarn add @heroui/styles@beta @heroui/react@beta

bun add @heroui/styles@beta @heroui/react@beta

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

新增功能

新组件

本次发布引入了 7 个 新的基础组件：

ButtonGroup：以一致的样式与间距将相关按钮分组。（文档）
DateField：日期输入字段，支持 label、description 与表单校验，基于 React Aria DateField 构建。（文档）
ErrorMessage：底层的错误信息组件，用于在非表单组件中展示错误。（文档）
ScrollShadow：通过视觉阴影提示可滚动内容溢出，并可自动检测滚动位置。（文档）
SearchField：带有内置搜索图标与清除按钮的搜索输入字段。（文档）
TagGroup：一组可聚焦的标签，支持键盘导航、选择与删除。（文档）
TimeField：时间输入字段，支持 label、description 与表单校验，基于 React Aria TimeField 构建。（文档）

ButtonGroup

import {
  ChevronDown,
  ChevronLeft,
  ChevronRight,
  CodeFork,

DateField

日期

mmddyyyy

"use client";

import {DateField, Label} from "@heroui/react";

export function Basic() {

ErrorMessage

"use client";

import type {Key} from "@heroui/react";

import {Description, ErrorMessage, Label, Tag, TagGroup} from "@heroui/react";

SearchField

搜索

import {Label, SearchField} from "@heroui/react";

export function Basic() {
  return (
    <SearchField name="search">

ScrollShadow

垂直

段落 1：Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.

段落 2：Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.

段落 3：Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.

段落 4：Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.

段落 5：Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.

段落 6：Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.

段落 7：Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.

段落 8：Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.

段落 9：Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.

段落 10：Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien.

水平

连接未来

今天 18:30

连接未来

今天 18:30

连接未来

今天 18:30

连接未来

今天 18:30

连接未来

今天 18:30

连接未来

今天 18:30

连接未来

今天 18:30

连接未来

今天 18:30

连接未来

今天 18:30

连接未来

今天 18:30

import {Card, ScrollShadow} from "@heroui/react";

const images = [
  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/robot1.jpeg",
  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg",

"use client";

import {PlanetEarth, Rocket, ShoppingBag, SquareArticle} from "@gravity-ui/icons";
import {Tag, TagGroup} from "@heroui/react";

TimeField

时间

––––AM

"use client";

import {Label, TimeField} from "@heroui/react";

export function Basic() {

全宽支持

为表单与输入组件新增 fullWidth 支持，可以让它们撑满容器的整个宽度。这在构建一致的表单布局与响应式设计时尤其有用。

支持的组件：

组件改进

分隔线控制增强

为 Tabs、ButtonGroup 与 Accordion 组件新增 hideSeparator 支持，可隐藏条目之间的分隔线，呈现更简洁、更纯粹的外观。

Tabs：

<Tabs hideSeparator>
  <Tabs.ListContainer>
    <Tabs.List aria-label="Options">
      <Tabs.Tab id="overview">Overview<Tabs.Indicator /></Tabs.Tab>
      <Tabs.Tab id="analytics">Analytics<Tabs.Indicator /></Tabs.Tab>
    </Tabs.List>
  </Tabs.ListContainer>
</Tabs>

ButtonGroup：

<ButtonGroup hideSeparator>
  <Button>First</Button>
  <Button>Second</Button>
  <Button>Third</Button>
</ButtonGroup>

Accordion：

<Accordion hideSeparator>
  <Accordion.Item>
    <Accordion.Heading>
      <Accordion.Trigger>Item 1</Accordion.Trigger>
    </Accordion.Heading>
    <Accordion.Panel>
      <Accordion.Body>Content</Accordion.Body>
    </Accordion.Panel>
  </Accordion.Item>
</Accordion>

文档图标集成

将 @gravity-ui/icons 集成到文档组件中，统一图标渲染，同时改进了 SSR 支持并提升了性能。

依赖更新

React Aria Components v1.14.0

将 React Aria Components 升级到 v1.14.0。本次升级包含：

增强：

SearchField：新增 isReadOnly 与 isRequired 渲染属性
Tooltip：新增 shouldCloseOnPress 属性
Tabs：支持在 tab 面板之间进行动画过渡
其他：useControlledState 现已在 setState 回调中提供支持

修复：

ComboBox：修复 VoiceOver 不读取 ListBox 项 aria-label 的问题
日期与时间：增强了对 absolute 日期与日期时间字符串的错误处理
NumberField：在移动端滚动时不再误触发递增 / 递减
Overlay：修复了设置 boundary container 时 overlay 定位与 flip 的问题
Table：修复了在键盘导航期间进行拖放时的崩溃问题
其他多项 bug 修复与改进

完整变更请参阅 React Aria Components v1.14.0 发布说明。

其他依赖升级

@internationalized/date：3.10.0 → 3.10.1
@radix-ui/react-avatar：1.1.10 → 1.1.11
tailwind-merge：3.3.1 → 3.4.0
tailwind-variants：3.1.1 → 3.2.2

样式修复

表单组件的禁用状态

修复了 Input 与 TextArea 组件的禁用状态样式。

样式优化

提高选择器精确度：增强 CSS 选择器特异性，让样式隔离更好、性能更优
动画增强：改进了多个组件的动画性能与流畅度
新增 no-highlight 工具类：新增 no-highlight 工具类，用于防止交互元素中的文字被选中，从而提升体验
优化 will-change 属性：在多个组件中调整 will-change CSS 属性，以获得更好的动画性能
移除全局滚动条样式：移除了全局滚动条样式，避免与自定义滚动条实现冲突，并修复了 modal / overlay 的交互问题

⚠️ 破坏性变更

backdropVariant / variant prop 的取值已从 "solid" 重命名为 "opaque"，以提升语义清晰度——「opaque」（不透明）更准确地描述了遮罩的视觉外观。

迁移：

将 AlertDialog 中所有 backdropVariant="solid" 替换为 backdropVariant="opaque"，将 Modal 中所有 variant="solid" 替换为 variant="opaque"：

// Before
<AlertDialog.Backdrop backdropVariant="solid">
  <AlertDialog.Container>
    {/* content */}
  </AlertDialog.Container>
</AlertDialog.Backdrop>

<Modal.Backdrop variant="solid">
  <Modal.Container>
    {/* content */}
  </Modal.Container>
</Modal.Backdrop>

// After
<AlertDialog.Backdrop backdropVariant="opaque">
  <AlertDialog.Container>
    {/* content */}
  </AlertDialog.Container>
</AlertDialog.Backdrop>

<Modal.Backdrop variant="opaque">
  <Modal.Container>
    {/* content */}
  </Modal.Container>
</Modal.Backdrop>

可用的 backdrop 变体：

"opaque" —— 深色不透明遮罩，完全遮挡背景（即此前的 "solid"）
"blur" —— 模糊遮罩，柔和地遮挡背景
"transparent" —— 透明遮罩，保持背景可见

移除 `asChild` prop

为提供更清晰的 API、更强的类型安全性以及更简单的使用方式，组件中的 asChild 模式已被移除。

关于组件组合模式的更多细节，请参阅组合指南。

Bug 修复

修复了 isInvalid 样式在 surface 背景上使用相关组件时的表现
修复了 AlertDialog 与 Modal 关闭后重新渲染的问题
修复了浮层关闭时未能正确清理的问题
修复了文档中 Storybook 链接与导航的问题

链接

贡献者

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

T@tianenpang J@jrgarciadev W@wingkwong

v3.0.0-beta.3

安装

新增功能

新组件

ButtonGroup

DateField

ErrorMessage

SearchField

ScrollShadow

垂直

水平

连接未来

连接未来

连接未来

连接未来

连接未来

连接未来

连接未来

连接未来

连接未来

连接未来

TimeField

全宽支持

组件改进

分隔线控制增强

文档图标集成

依赖更新

React Aria Components v1.14.0

其他依赖升级

样式修复

表单组件的禁用状态

样式优化

⚠️ 破坏性变更

移除 `asChild` prop

Bug 修复

链接

贡献者

本页目录