2025 年 10 月 15 日

此版本引入了一系列基于表单的组件、表单字段 token，重新组织了 Storybook，并对各组件之间的 data-slot 标识做了统一对齐。

安装

升级到最新版本：

npm i @heroui/styles@alpha @heroui/react@alpha

pnpm add @heroui/styles@alpha @heroui/react@alpha

yarn add @heroui/styles@alpha @heroui/react@alpha

bun add @heroui/styles@alpha @heroui/react@alpha

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

新增功能

基于表单的组件

我们引入了一整套基于 React Aria Components 构建的表单类组件，为构建表单提供了无障碍且可组合的基础构件。这些组件包括 Description、FieldError、Fieldset、Form、Input、Label、RadioGroup、TextField 与 TextArea。

Description

邮箱我们不会将你的邮箱分享给任何人。

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

export function Basic() {
  return (
    <div className="flex flex-col gap-1">

FieldError

用户名用户名至少需要 3 个字符

"use client";

import {FieldError, Input, Label, TextField} from "@heroui/react";
import {useState} from "react";

Fieldset

"use client";

import {FloppyDisk} from "@gravity-ui/icons";
import {
  Button,

Form

"use client";

import {Check} from "@gravity-ui/icons";
import {Button, Description, FieldError, Form, Input, Label, TextField} from "@heroui/react";

Input

import {Input} from "@heroui/react";

export function Basic() {
  return <Input aria-label="姓名" className="w-64" placeholder="输入你的姓名" />;
}

Label

姓名

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

export function Basic() {
  return (
    <div className="flex flex-col gap-1">
      <Label htmlFor="name">姓名</Label>
      <Input className="w-64" id="name" placeholder="输入你的姓名" type="text" />
    </div>
  );
}

RadioGroup

选择套餐选择最适合你的套餐

基础版每月包含 100 条消息

高级版每月包含 200 条消息

商业版无限消息

import {Description, Label, Radio, RadioGroup} from "@heroui/react";

export function Basic() {
  return (
    <RadioGroup defaultValue="premium" name="plan">

TextField

Component demo "text-field-basic" not found. Make sure the demo is registered in the demos index.

TextArea

import {TextArea} from "@heroui/react";

export function Basic() {
  return (
    <TextArea

表单字段 token

引入 --field-* 表单字段 token，确保各表单组件之间样式保持一致。--field-* 变量的具体说明请参阅主题。

Storybook 重新组织

按类别重新组织了 Storybook，方便导航与组件查找。

Skeleton 动画 token

🚧 破坏性变更： 为了与其他组件 token 保持一致，Skeleton 中的 --skeleton-default-animation-type 已重命名为 --skeleton-animation。

data-slot 对齐

我们统一了各组件的 data-slot 标识，使样式与定制更加一致。这项标准化让通过 CSS 选择器定位特定组件部件变得更容易，整体上也优化了自定义组件样式时的开发体验。

组件现在使用一致的 data-slot 属性，例如：

data-slot="base" —— 用于根元素
data-slot="label" —— 用于标签文本
data-slot="description" —— 用于描述文本
data-slot="error" —— 用于错误信息

这样在所有表单组件中都能用可预期的方式进行 CSS 定位：

.radio {
  [data-slot="label"] {
    /* Styles apply to radio labels */
  }
}

文档改进

组件文档

Link：新增 anatomy 与带图标的示例，更新了 Link 与 Link.Icon 的 prop 章节。
Description、FieldError、Fieldset、Form、Input、Label、RadioGroup、TextField，以及 TextArea：附带使用示例的全新文档

迁移指南

Skeleton 组件迁移

更新动画 token：
- 将 --skeleton-default-animation-type 替换为 --skeleton-animation

链接

贡献者

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

v3.0.0-alpha.34

安装