2025 年 11 月 6 日

此版本对 HeroUI v3 进行了全面重新设计，将 v2 的美观与动效与 v3 的简洁性融为一体。所有组件均经过重新设计，新增 8 个组件，并对设计系统进行了改进，包括更完善的颜色 token、阴影体系与整体架构。

安装

升级到最新版本：

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 服务器。

[data-input-otp] { --nojs-bg: white !important; --nojs-fg: black !important; background-color: var(--nojs-bg) !important; color: var(--nojs-fg) !important; caret-color: var(--nojs-fg) !important; letter-spacing: .25em !important; text-align: center !important; border: 1px solid var(--nojs-fg) !important; border-radius: 4px !important; width: 100% !important; } @media (prefers-color-scheme: dark) { [data-input-otp] { --nojs-bg: black !important; --nojs-fg: white !important; } }

没有收到验证码？

重新发送

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

export function Basic() {
  return (
    <div className="flex w-[280px] flex-col gap-2">

ListBox

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

export function Default() {
  return (
    <ListBox aria-label="用户" className="w-[220px]" selectionMode="single">

Select

州

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

export function Default() {
  return (
    <Select className="w-[256px]" placeholder="请选择">

Slider

音量30

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

export function Default() {
  return (
    <Slider className="w-full max-w-xs" defaultValue={30}>

Surface

默认

表面内容

这是默认表面变体，使用 bg-surface 样式。

次要

表面内容

这是次要表面变体，使用 bg-surface-secondary 样式。

第三

表面内容

这是第三表面变体，使用 bg-surface-tertiary 样式。

透明

表面内容

这是透明表面变体，无背景，适用于遮罩层和自定义背景的卡片。

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

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

组件 API 改进

多个组件的 API 都得到了改进：

Link：新增 underline 与 underlineOffset prop，支持更细粒度的定制

立即行动

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

export function LinkBasic() {
  return (
    <Link href="#">
      立即行动
      <Link.Icon />
    </Link>
  );
}

Card：变体与样式系统得到改进

Indie Hackers

148 位成员

AI Builders

362 位成员

NEO

家用机器人

连接未来

今天 18:30

牛油果黑客松

周三 16:30

Sound Electro｜超越艺术

周五 20:00

import {CircleDollar} from "@gravity-ui/icons";
import {Avatar, Button, Card, CloseButton, Link} from "@heroui/react";

export function WithImages() {
  return (

Chip：新增尺寸变体并改进了颜色系统

默认强调成功警告危险

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

export function ChipBasic() {
  return (
    <div className="flex flex-wrap items-center gap-3">

Switch：从底层重新设计，视觉与动画都得到优化

启用通知

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

export function Basic() {
  return (
    <Switch>

RadioGroup：从底层重新设计，API 与样式更佳

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

基础版每月包含 100 条消息

高级版每月包含 200 条消息

商业版无限消息

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

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

灵活的组件模式

HeroUI 现在支持更灵活的组件写法。复合组件可以带 .Root 也可以不带 .Root，也可以使用命名导出——三种写法表现完全一致。

可用模式：

import { Avatar } from "@heroui/react"

// 1. Compound pattern (no .Root needed) - recommended
<Avatar>
  <Avatar.Image src="/avatar.jpg" alt="User" />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>

// 2. Compound pattern with .Root - still supported
<Avatar.Root>
  <Avatar.Image src="/avatar.jpg" alt="User" />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar.Root>

// 3. Named exports
import { AvatarRoot, AvatarImage, AvatarFallback } from "@heroui/react"

<AvatarRoot>
  <AvatarImage src="/avatar.jpg" alt="User" />
  <AvatarFallback>JD</AvatarFallback>
</AvatarRoot>

简单组件（如 Button）的写法也完全一致：

import { Button } from "@heroui/react"

// No .Root needed
<Button>Label</Button>

// Or with .Root
<Button.Root>Label</Button.Root>

// Or named export
import { ButtonRoot } from "@heroui/react"
<ButtonRoot>Label</ButtonRoot>

你也可以在同一个组件中混用复合写法与命名导出：

import { Avatar, AvatarFallback } from "@heroui/react"

<Avatar>
  <Avatar.Image src="/avatar.jpg" alt="User" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

由此带来的好处：

更简洁的 API：主组件不再强制要求 .Root 后缀
灵活性：可以在「复合写法」、「带 .Root 的复合写法」与「命名导出」之间自由选择
向后兼容：.Root 写法依然可用
命名一致性：统一了命名约定（例如使用「Container」而非「Wrapper」）

全局动画控制

HeroUI 现在通过 data-reduce-motion 属性提供了便捷的全局动画控制方式。只需在 <html> 或 <body> 标签上加上 data-reduce-motion="true"，即可禁用整个应用中的所有动画。

<!DOCTYPE html>
<html data-reduce-motion="true">
  <!-- All HeroUI animations will be disabled -->
</html>

HeroUI 会自动通过 prefers-reduced-motion 媒体查询尊重用户的动画偏好，并扩展了 Tailwind 的 motion-reduce: 变体，使其同时支持系统偏好与基于 data 属性的手动控制。这样既能灵活控制动画，也能符合无障碍最佳实践。

了解更多关于动画与动效偏好的内容，请参阅动画文档。

⚠️ 破坏性变更

设计系统变量

Panel → Surface 与 Overlay

--panel 变量已被替换为 --surface 与 --overlay，以更好地区分非浮层组件（Card、Accordion）与浮层组件（Tooltip、Popover、Modal）。

之前：

--panel: var(--white);
--panel-foreground: var(--foreground);
--shadow-panel: 0 0 1px 0 rgba(0, 0, 0, 0.3) inset, 0 2px 8px 0 rgba(0, 0, 0, 0.08);

之后：

--surface: var(--white);
--surface-foreground: var(--foreground);
--overlay: var(--white);
--overlay-foreground: var(--foreground);
--shadow-surface: 0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06);
--shadow-overlay: 0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09);

迁移：

非浮层组件请将 bg-panel 替换为 bg-surface
浮层组件请将 bg-panel 替换为 bg-overlay
将 shadow-panel 替换为 shadow-surface 或 shadow-overlay
将 --color-panel 替换为 --color-surface 或 --color-overlay

Surface 层级简化

--surface-1、--surface-2 与 --surface-3 变量已被移除。Surface 各层级现在通过 color-mix 自动从 --surface 计算得出，因此你只需声明基础的 surface 颜色。

之前（手动声明）：

--surface-1: var(--background);
--surface-2: var(--color-neutral-100);
--surface-3: var(--color-neutral-200);

之后（自动计算）：

/* You only declare the base surface */
--surface: var(--white);
--surface-foreground: var(--foreground);

/* HeroUI automatically calculates these using color-mix */
--color-surface-secondary: color-mix(in oklab, var(--surface) 94%, var(--surface-foreground) 6%);
--color-surface-tertiary: color-mix(in oklab, var(--surface) 92%, var(--surface-foreground) 8%);
--color-surface-quaternary: color-mix(in oklab, var(--surface) 86%, var(--surface-foreground) 14%);

自定义：

可以通过 Tailwind 的 @theme 指令覆盖默认的计算结果：

@theme inline {
  --color-surface-secondary: color-mix(in oklab, var(--surface) 96%, var(--surface-foreground) 4%);
  --color-surface-tertiary: color-mix(in oklab, var(--surface) 94%, var(--surface-foreground) 6%);
  --color-surface-quaternary: color-mix(in oklab, var(--surface) 90%, var(--surface-foreground) 10%);
}

迁移：

将 bg-surface-1 替换为 bg-surface（基础 surface）
将 bg-surface-2 替换为 bg-surface-secondary（自动计算）
将 bg-surface-3 替换为 bg-surface-tertiary（自动计算）

同样的自动计算模式也适用于：

背景色阶：从 --background 计算 → background-secondary、background-tertiary、background-quaternary
柔和色：从状态色计算 → accent-soft、danger-soft、warning-soft、success-soft

边框宽度默认值变更

默认边框宽度已从 1px 改为 0px。边框现在改为按需启用，而不是默认存在。

之前：

--border-width: 1px;

之后：

--border-width: 0px; /* no border by default */

迁移：

如果你的样式依赖默认边框，请在自定义样式中显式设置 border-width
表单字段现在默认使用 transparent 边框

边框颜色默认值变更

默认边框颜色的不透明度已从 15% 改为 0%（透明）。

之前：

--border: oklch(0 0 0 / 15%);

之后：

--border: oklch(0 0 0 / 0%);

字段边框默认值：

--field-border: transparent; /* no border by default on form fields */

阴影系统更新

阴影系统已被完全重新设计，为 surface 与 overlay 各自提供独立的阴影。

之前：

--panel-shadow: 0 0 1px 0 rgba(0, 0, 0, 0.3) inset, 0 2px 8px 0 rgba(0, 0, 0, 0.08);
--field-shadow: 0 0 0 0 rgba(255, 255, 255, 0.1) inset, 0 1px 2px 0 rgba(0, 0, 0, 0.05);

之后（浅色模式）：

--surface-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06);
--overlay-shadow: 0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09);
--field-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06), 0 0 1px 0 rgba(0, 0, 0, 0.06);

之后（深色模式）：

--surface-shadow: 0 0 0 0 transparent inset; /* No shadow on dark mode */
--overlay-shadow: 0 0 0 0 transparent inset; /* No shadow on dark mode */
--field-shadow: 0 0 0 0 transparent inset; /* Transparent shadow to allow ring utilities to work */

强调色更新

强调色经过更新，对比度与视觉吸引力都有所提升。

之前：

--accent: var(--color-neutral-950);
--accent-foreground: var(--snow);

之后：

--accent: oklch(0.6204 0.195 253.83);
--accent-foreground: var(--snow);

状态颜色优化

success、warning 与 danger 颜色经过优化，一致性与对比度都更佳。

Success：

之前： oklch(0.5503 0.1244 153.56)
之后： oklch(0.7329 0.1935 150.81)
浅色模式下，前景色从 var(--snow) 改为 var(--eclipse)

Warning：

之前： oklch(0.7186 0.1521 64.85)
之后： oklch(0.7819 0.1585 72.33)（浅色），oklch(0.8203 0.1388 76.34)（深色）

Danger：

之前： oklch(0.6259 0.1908 29.19)
之后： oklch(0.6532 0.2328 25.74)（浅色），oklch(0.594 0.1967 24.63)（深色）

组件 API 变更

Chip 组件

Chip 组件的 type prop 已重命名为 color，同时新增 size prop，并引入了新的 soft 变体。

之前：

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

<Chip type="danger" variant="secondary">Label</Chip>

之后：

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

<Chip color="danger" variant="soft" size="md">Label</Chip>

迁移：

将 type prop 替换为 color prop
使用 size prop（sm、md、lg）控制 Chip 尺寸
soft 变体提供低调的外观，适用于不那么突出的 Chip

Link 组件

Link 组件现在支持 underline 与 underlineOffset prop，并加入了对 asChild 的支持。

之前：

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

<Link href="#">Link text</Link>

之后：

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

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

新增 prop：

underline："none" | "hover" | "always" —— 控制下划线的可见性
underlineOffset：number —— 控制下划线相对文本的偏移

类型引用语法

由于采用了双模式实现，通过命名空间语法引用类型的方式不再支持。请改用对象样式语法或具名类型导入。

之前（不再可用）：

type AvatarProps = Avatar.RootProps

之后（方式 1 —— 对象样式语法）：

type AvatarProps = Avatar["RootProps"]

之后（方式 2 —— 具名类型导入，推荐）：

import type { AvatarRootProps } from "@heroui/react"

type AvatarProps = AvatarRootProps

此变更会影响访问 prop 类型的所有复合组件。

Tabs 组件重命名

为保持一致性，Tabs 组件的包装元素已重命名：

复合属性：Tabs.ListWrapper → Tabs.ListContainer
命名导出：TabListWrapper → TabListContainer
CSS 类：.tabs__list-wrapper → .tabs__list-container
data 属性：data-slot="tabs-list-wrapper" → data-slot="tabs-list-container"

迁移：

请查找并替换所有 TabListWrapper，将其改为 TabListContainer：

# Component usage
TabListWrapper → TabListContainer
Tabs.ListWrapper → Tabs.ListContainer

# CSS selectors (if using custom styles)
.tabs__list-wrapper → .tabs__list-container
[data-slot="tabs-list-wrapper"] → [data-slot="tabs-list-container"]

已移除的变量

以下变量已被移除：

--panel → 改用 --surface 或 --overlay
--panel-foreground → 改用 --surface-foreground 或 --overlay-foreground
--surface-1、--surface-2、--surface-3 → 改用背景色阶或 surface 层级
--accent-soft → 改用 --color-accent-soft（现已自动计算）
--radius-panel 与 --radius-panel-inner → 改用标准的 radius 取值

设计系统更新

全新的色彩系统

Surface 与 Overlay 概念

设计系统现在区分两类带高度的组件：

Surface：用于直接放置在页面上的非浮层组件，如 Card、Accordion、Disclosure Group
Overlay：用于浮在页面之上的浮层组件，如 Tooltip、Popover、Modal、Menu

这种区分带来：

更好的视觉层级
更合适的阴影深度
更优的深色模式对比度
更清晰的组件语义

自动计算的色彩系统

HeroUI 现在使用 CSS color-mix 自动计算各种色阶以及柔和色变体。你只需声明基础颜色，剩下的交给 HeroUI 处理。

背景色阶

背景色阶会自动从 --background 计算：

/* You only declare the base */
--background: oklch(0.9702 0 0);
--foreground: var(--eclipse);

/* HeroUI automatically calculates these */
--color-background-secondary: color-mix(in oklab, var(--color-background) 96%, var(--color-foreground) 4%);
--color-background-tertiary: color-mix(in oklab, var(--color-background) 92%, var(--color-foreground) 8%);
--color-background-quaternary: color-mix(in oklab, var(--color-background) 86%, var(--color-foreground) 14%);

Surface 层级

Surface 各层级会自动从 --surface 计算：

/* You only declare the base */
--surface: var(--white);
--surface-foreground: var(--foreground);

/* HeroUI automatically calculates these */
--color-surface-secondary: color-mix(in oklab, var(--surface) 94%, var(--surface-foreground) 6%);
--color-surface-tertiary: color-mix(in oklab, var(--surface) 92%, var(--surface-foreground) 8%);
--color-surface-quaternary: color-mix(in oklab, var(--surface) 86%, var(--surface-foreground) 14%);

柔和色变体

柔和色变体会自动从状态色计算：

/* You declare the base status colors */
--accent: oklch(0.6204 0.195 253.83);
--danger: oklch(0.6532 0.2328 25.74);
--warning: oklch(0.7819 0.1585 72.33);
--success: oklch(0.7329 0.1935 150.81);

/* HeroUI automatically calculates these at 15% opacity */
--color-accent-soft: color-mix(in oklab, var(--color-accent) 15%, transparent);
--color-danger-soft: color-mix(in oklab, var(--color-danger) 15%, transparent);
--color-warning-soft: color-mix(in oklab, var(--color-warning) 15%, transparent);
--color-success-soft: color-mix(in oklab, var(--color-success) 15%, transparent);

每个柔和色变体都包含悬停态（20% 不透明度）以及对应的前景色，以保证合适的对比度。

自定义：

可以通过 Tailwind 的 @theme 指令覆盖任意自动计算结果：

@theme inline {
  /* Adjust surface levels */
  --color-surface-secondary: color-mix(in oklab, var(--surface) 96%, var(--surface-foreground) 4%);

  /* Adjust soft colors */
  --color-accent-soft: color-mix(in oklab, var(--color-accent) 20%, transparent);
}

这套自动计算系统减少了你需要管理的变量数量，同时在需要时仍能完全自定义。

阴影系统

阴影系统经过重新设计，提供：

为 surface 与 overlay 提供各自独立的阴影
更好的层次感
深色模式支持（透明阴影）
一致的字段阴影

阴影会自动适配浅色与深色模式，为每种主题提供合适的层次提示。

焦点系统

焦点颜色现在使用强调色，以保持一致性：

--focus: var(--accent);

这样既能让焦点指示器与你的品牌色一致，也能保留无障碍能力。

排版 token

部分与排版相关的变量已被移除，转而推荐直接使用 Tailwind 的排版工具类。设计系统现在专注于颜色与间距 token，将排版交给 Tailwind 处理。

迁移指南

第 1 步：更新设计系统变量

将旧的 panel 变量替换为 surface / overlay：

/* Before */
.my-card {
  background: var(--panel);
  box-shadow: var(--shadow-panel);
}

/* After */
.my-card {
  background: var(--surface);
  box-shadow: var(--shadow-surface);
}

.my-tooltip {
  background: var(--overlay);
  box-shadow: var(--shadow-overlay);
}

第 2 步：更新 surface 层级

Surface 层级现在会自动从 --surface 计算得出，因此无需手动声明。直接使用新的工具类即可：

/* Before */
.bg-surface-1 → .bg-surface (base surface)
.bg-surface-2 → .bg-surface-secondary (auto-calculated)
.bg-surface-3 → .bg-surface-tertiary (auto-calculated)

/* You can also use background shades */
.bg-surface-2 → .bg-background-secondary (auto-calculated from --background)
.bg-surface-3 → .bg-background-tertiary (auto-calculated from --background)

说明： Surface 层级（surface-secondary、surface-tertiary 等）会基于你的 --surface 颜色自动计算。除非你想自定义计算方式，否则不需要手动声明任何 CSS 变量。

第 3 步：更新组件 props

更新 Chip 与 Link 组件：

// Chip: type → color, add size if needed
<Chip type="danger" /> → <Chip color="danger" size="md" />

// Link: Add underline props if customizing underlines
<Link href="#">Text</Link> // Still works, underline props are optional

第 4 步：简化组件写法（可选）

如果你在 v3.0.0-alpha.35 中已经采用了 .Root 后缀，现在可以将其移除以简化代码：

之前（v3.0.0-alpha.35）：

<Avatar.Root>
  <Avatar.Image src="..." alt="..." />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar.Root>

之后（更简洁）：

<Avatar>
  <Avatar.Image src="..." alt="..." />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>

说明： 如果你更喜欢 .Root 写法，它仍然可用。

第 5 步：更新类型引用

如果你之前用命名空间语法来引用类型，请改用对象样式语法或具名导入：

之前：

type ButtonProps = Button.RootProps

之后（方式 1 —— 对象样式）：

type ButtonProps = Button["RootProps"]

之后（方式 2 —— 具名导入，推荐）：

import type { ButtonRootProps } from "@heroui/react"

type ButtonProps = ButtonRootProps

第 6 步：更新 Tabs 组件

将 TabListWrapper 替换为 TabListContainer：

之前：

import { Tabs } from "@heroui/react"

<Tabs.Root>
  <Tabs.ListWrapper>
    <Tabs.List>
      <Tabs.Tab id="home">Home<Tabs.Indicator /></Tabs.Tab>
    </Tabs.List>
  </Tabs.ListWrapper>
  <Tabs.Panel id="home">Content</Tabs.Panel>
</Tabs.Root>

之后：

import { Tabs } from "@heroui/react"

<Tabs>
  <Tabs.ListContainer>
    <Tabs.List>
      <Tabs.Tab id="home">Home<Tabs.Indicator /></Tabs.Tab>
    </Tabs.List>
  </Tabs.ListContainer>
  <Tabs.Panel id="home">Content</Tabs.Panel>
</Tabs>

第 7 步：处理边框相关变更

如果你的自定义样式依赖默认边框：

/* Add explicit borders where needed */
.my-component {
  border-width: 1px;
  border-color: var(--color-border);
}

第 8 步：更新状态颜色

如果你曾经定制过状态颜色，请查阅新的取值并按需调整你的自定义主题：

/* Check if your custom status colors need updates */
--success: oklch(0.7329 0.1935 150.81); /* New value */
--warning: oklch(0.7819 0.1585 72.33); /* New value */
--danger: oklch(0.6532 0.2328 25.74); /* New value */

自动化迁移

对于较大的代码库，可以借助查找 / 替换：

# Panel → Surface
--panel → --surface
bg-panel → bg-surface
shadow-panel → shadow-surface

# Panel → Overlay (for floating components)
--panel → --overlay (where appropriate)
bg-panel → bg-overlay (for tooltips, popovers, etc.)
shadow-panel → shadow-overlay (for floating components)

# Chip type prop
type=" → color="

# Surface levels
bg-surface-1 → bg-surface
bg-surface-2 → bg-surface-secondary
bg-surface-3 → bg-surface-tertiary

# Tabs component
TabListWrapper → TabListContainer
Tabs.ListWrapper → Tabs.ListContainer

# Type references
Component.RootProps → Component["RootProps"] or use named imports

简单组件：Button、Link、Spinner、Chip、Kbd
复合组件：Accordion、Avatar、Card、Disclosure、Fieldset、Popover、RadioGroup、Switch、Tabs、Tooltip

以上所有组件都可以使用三种写法中的任意一种：不带 .Root 的复合写法、带 .Root 的复合写法，或具名导出。

HeroUI Pro

HeroUI Pro 正基于全新的设计系统从零进行重塑。新版 Pro 将带来：

基于 HeroUI v3 构建的新组件
Tailwind CSS v4 原生支持
基于 CSS 的原生动画
更强的可定制能力

我们将很快分享更多更新。

路线图

我们正以发布稳定版本为目标，计划在 2025 年的 第四季度 完成。本次 beta 让我们距离这个目标更进一步：

更完整的组件集合
更精炼的设计系统
更佳的开发者体验
更好的性能

v3.0.0-beta.1

表面内容

表面内容

表面内容

表面内容

成为 ACME 创作者！

现已支持加密货币提现

NEO

连接未来

牛油果黑客松

Sound Electro｜超越艺术

本页目录