v3.0.0-beta.4

此版本引入了用于可视化主题定制的全新 主题构建器，三个新组件（Autocomplete、Breadcrumbs、Toast），为 Tabs 添加 secondary 变体，为 Input 与 InputGroup 添加 primary / secondary 变体，InputGroup 新增对 TextArea 的支持，以及 ⚠️ 破坏性变更：移除 Link 的下划线变体，并从表单组件中移除 isInSurface prop。

安装

升级到最新版本：

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

新增功能

主题构建器

我们很高兴推出 主题构建器 —— 用于创建与定制 HeroUI 主题的强大可视化工具。可在实时预览中构建你专属的主题，并导出可直接使用的 CSS。

主要特性：

• 可视化颜色编辑：通过 OKLCH 颜色选择器以及直观的亮度、色度、色相滑块来调整颜色
• 实时预览：在实时组件预览中立即查看你的修改
• 自定义强调色：定义你的品牌色，并观察它如何贯穿到所有组件
• 预设主题：从精选预设（如 Default、Airbnb、Coinbase、Discord）入手
• 导出即可用：生成 CSS 变量，直接复制到你的项目即可
• 浅色与深色模式：可联动也可独立地同时定制两套主题
• 键盘快捷键：支持撤销 / 重做以及快速操作，提升工作流效率

立即在 v3.heroui.com/themes 上试用。

新组件

本次发布共引入 3 个 新的基础组件：

• Autocomplete：将 Select 与过滤功能结合，让用户可以在选项列表中搜索并选择。（文档）
• Breadcrumbs：导航面包屑，用于展示当前页面在层级结构中的位置。（文档）
• Toast：用于展示临时通知与消息，支持自动关闭以及自定义放置位置。（文档）

Autocomplete

"use client";

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

import {

Breadcrumbs

"use client";

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

export default function BreadcrumbsBasic() {

Toast

"use client";

import {HardDrive, Persons} from "@gravity-ui/icons";
import {Button, toast} from "@heroui/react";

组件改进

Tabs 的 secondary 变体

为 Tabs 新增 secondary 变体，使用下划线指示器样式。该变体同时支持水平与垂直方向。

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

export function Secondary() {
  return (
    <Tabs className="w-full max-w-md" variant="secondary">

用法：

<Tabs variant="secondary">
  <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.Panel id="overview">Content</Tabs.Panel>
  <Tabs.Panel id="analytics">Content</Tabs.Panel>
</Tabs>

Input 变体

为 Input 组件新增 primary 与 secondary 变体：

• primary（默认）：带阴影的标准样式，适用于大多数场景
• secondary：不带阴影的低调变体，适合在 Surface 组件内部使用

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

export function Variants() {
  return (
    <div className="flex w-[240px] flex-col gap-2">
      <Input fullWidth placeholder="主要输入框" variant="primary" />
      <Input fullWidth placeholder="次要输入框" variant="secondary" />
    </div>
  );
}

InputGroup 增强

InputGroup 组件获得多项改进：

TextArea 支持：可使用 InputGroup.TextArea 来构建带有 prefix 与 suffix 的多行文本输入。

"use client";

import {ArrowUp, At, Microphone, PlugConnection, Plus} from "@gravity-ui/icons";
import {Button, InputGroup, Kbd, Spinner, TextField, Tooltip} from "@heroui/react";
import {useState} from "react";

变体：新增与 Input 组件相匹配的 primary 与 secondary 变体。

import {Envelope} from "@gravity-ui/icons";
import {InputGroup, Label, TextField} from "@heroui/react";

export function Variants() {
  return (

Button 与 ButtonGroup 的 outline 变体

为 Button 与 ButtonGroup 同时新增 outline 变体，用于呈现描边样式。

import {Button, ButtonGroup} from "@heroui/react";

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

AlertDialog 尺寸支持

为 AlertDialog 组件新增尺寸支持，让你可以控制对话框的大小。

"use client";

import {Rocket} from "@gravity-ui/icons";
import {AlertDialog, Button} from "@heroui/react";

Checkbox 动画改进

为 Checkbox 提供更快的动画与更粗的描边宽度，反馈更明显。

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

export function Basic() {
  return (
    <Checkbox id="basic-terms">

Link 的文本装饰

Link 组件现在使用 Tailwind CSS 类来设置文本装饰，而不再依赖内置变体。这样既更灵活，也更贴合 Tailwind 的使用习惯。

可用的 Tailwind 工具类：

• underline —— 始终显示下划线
• no-underline —— 移除下划线
• hover:underline —— 仅在悬停时显示下划线
• decoration-primary、decoration-secondary 等 —— 设置下划线颜色
• decoration-1、decoration-2、decoration-4 —— 控制下划线粗细
• underline-offset-1、underline-offset-2 等 —— 调整下划线偏移

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

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

⚠️ 破坏性变更

Link 组件 —— 移除下划线相关变体

Link 组件内置的 underline 与 underlineOffset prop 已被移除。请改用 Tailwind CSS 类来控制文本装饰。

之前：

<Link href="#" underline="hover" underlineOffset={4}>
  Link text
</Link>

之后：

<Link href="#" className="hover:underline underline-offset-4">
  Link text
</Link>

可用的 Tailwind 类：

• underline、no-underline、hover:underline —— 装饰线
• decoration-primary、decoration-muted 等 —— 装饰线颜色
• decoration-solid、decoration-dashed、decoration-dotted —— 装饰线样式
• decoration-1、decoration-2、decoration-4 —— 装饰线粗细
• underline-offset-1、underline-offset-2、underline-offset-4 —— 下划线偏移

详见 Link 文档。

表单组件 —— 移除 isInSurface prop

isInSurface prop 以及自动 surface 检测已从基于表单的组件中移除。当你将表单组件放置在 Surface、Card 或其他基于 Surface 的容器中时，请改用 variant="secondary"。

之前：

<Surface>
  {/* Input automatically detected surface context */}
  <Input isInSurface />
</Surface>

之后：

<Surface>
  {/* Use variant="secondary" for surface backgrounds */}
  <Input variant="secondary" />
</Surface>

受影响的组件：

• Input
• InputGroup
• TextField
• TextArea
• SearchField
• NumberField
• DateField
• TimeField
• Select
• ComboBox
• Autocomplete

secondary 变体提供不带阴影的低调样式，更适合在 surface 背景上使用。

样式修复

• Button：更新 secondary 按钮颜色，提升视觉一致性
• Checkbox：优化动画速度并加粗描边，反馈更明显（详见 Checkbox 动画改进）
• Link：更新装饰线样式与过渡时长
• Focus Visible：在 focus-visible 选择器中加入 :not(:focus)，避免与 hover 状态冲突
• Separator：将固定样式仅应用到水平方向的分隔线

Bug 修复

• 修复使用按钮变体样式的 Link
• 修复 Safari 中 BEM 样式下 Fieldset 的 Flexbox 兼容性问题
• 修复 SearchField 在空状态时未正确禁用清除按钮的问题
• 修复 ButtonGroup 的 context 仅对直接子元素生效的问题
• 修复 ButtonGroup 中 BUTTON_GROUP_CHILD 重新导出的类型声明

依赖更新

直接从 React Aria Components 重新导出

HeroUI 现在直接从 react-aria-components 重新导出了一系列基元与工具，方便你访问。这些导出对于 React Aria 框架配置 尤其有用。

Provider：

• RouterProvider —— 配置 React Aria 的 Link 使用客户端路由器
• I18nProvider —— 设置 React Aria Components 使用的 locale

Hook 与工具：

• isRTL —— 检查某个 locale 是否为从右到左
• useLocale —— 访问当前 locale 与方向
• useFilter —— 对集合进行过滤与排序

组件：

• Collection —— 用于管理列表的集合组件
• ListBoxLoadMoreItem —— 用于加载更多条目的 ListBox 项

国际化工具：

• getLocalizationScript —— 获取用于服务端渲染的本地化脚本（来自 react-aria-components/i18n）

以上这些都可以直接从 @heroui/react 引入：

import {
  RouterProvider,
  I18nProvider,
  isRTL,
  useLocale,
  useFilter,
  getLocalizationScript
} from "@heroui/react";

链接

• 主题构建器
• 组件文档
• 设计系统 - Figma Kit v3（已更新）
• GitHub 仓库
• GitHub PR #6121

贡献者

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