2026 年 3 月 14 日

新增七个组件：Drawer、ToggleButton、ToggleButtonGroup、Meter、ProgressBar、ProgressCircle 与 Toolbar。Table 与 ListBox 支持虚拟化，ButtonGroup 新增 Separator 子组件并支持垂直方向，React Aria Components 升级到 v1.16.0。

安装

升级到最新版本：

npm i @heroui/styles@rc @heroui/react@rc

pnpm add @heroui/styles@rc @heroui/react@rc

yarn add @heroui/styles@rc @heroui/react@rc

bun add @heroui/styles@rc @heroui/react@rc

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

新增功能

新组件

Drawer：滑出式面板，支持拖拽关闭、4 种放置位置、多种背景遮罩变体以及可滚动的内容区（文档）
ToggleButton：选中 / 未选中两态的切换按钮，支持全部按钮变体以及仅图标模式（文档）
ToggleButtonGroup：单选或多选的切换按钮组，支持 attached / detached 布局以及方向设置（文档）
Meter：在已知范围内呈现某个数值——例如磁盘占用、密码强度、配额等（文档）
ProgressBar：线性进度条，支持确定 / 不确定态、多种颜色与自定义格式（文档）
ProgressCircle：基于 SVG 的环形进度条，可自定义轨道圆与填充圆（文档）
Toolbar：将按钮、切换控件与分隔线按水平或垂直方向组合在一起的工具栏组件（文档）

Drawer

带有背景遮罩的滑出式浮层面板，支持顶部 / 底部 / 左侧 / 右侧四种放置位置、拖拽关闭手势以及多种背景遮罩变体。复合部件包括：Trigger、Backdrop、Content、Dialog、Header、Heading、Body、Footer、Handle、CloseTrigger。

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

export function Basic() {
  return (
    <Drawer>

放置位置：

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

const PLACEMENT_LABELS = {
  bottom: "底部",
  left: "左侧",

配合表单使用：

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

export function WithForm() {
  return (
    <Drawer>

Toggle Button

具备状态的切换按钮，可在选中与未选中之间切换。支持全部按钮变体与尺寸、仅图标模式，以及受控 / 非受控两种使用方式。

import {Heart} from "@gravity-ui/icons";
import {ToggleButton} from "@heroui/react";

export function Basic() {
  return (

变体：

import {Heart} from "@gravity-ui/icons";
import {ToggleButton} from "@heroui/react";

export function Variants() {
  return (

Toggle Button Group

单选或多选的切换按钮组。支持 attached（连接式）与 detached（分离式）两种布局、垂直方向、整宽展示，以及一个 Separator 子组件。

import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";

export function Basic() {
  return (

选择模式：

单选

多选

import {
  Bold,
  Italic,
  Strikethrough,
  TextAlignCenter,

Attached 模式：

附着（默认）

分离

import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons";
import {ToggleButton, ToggleButtonGroup} from "@heroui/react";

export function Attached() {
  return (

Meter

在已知范围内呈现某个数值——例如磁盘占用、密码强度、配额等。复合部件包括：Root、Output、Track、Fill。

存储空间60%

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

export function Basic() {
  return (
    <Meter aria-label="存储空间" className="w-64" value={60}>

颜色：

默认50%

强调50%

成功50%

警告50%

危险50%

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

const colors = ["default", "accent", "success", "warning", "danger"] as const;

const COLOR_LABELS: Record<(typeof colors)[number], string> = {

Progress Bar

线性进度指示器，支持确定 / 不确定态、颜色变体、多种尺寸以及自定义数值显示。复合部件包括：Root、Output、Track、Fill。

加载中60%

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

export function Basic() {
  return (
    <ProgressBar aria-label="加载中" className="w-64" value={60}>

不确定态：

加载中…

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

export function Indeterminate() {
  return (
    <ProgressBar isIndeterminate aria-label="加载中" className="w-64">

Progress Circle

基于 SVG 的环形进度条，提供 TrackCircle 与 FillCircle 两个子组件，便于直接控制 SVG。同时支持确定与不确定态。

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

export function Basic() {
  return (
    <ProgressCircle aria-label="加载中" value={60}>

自定义 SVG：

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

export function CustomSvg() {
  return (
    <div className="flex items-end gap-6">

将按钮、切换按钮与分隔线组合到一个具备无障碍语义的工具栏中。支持水平或垂直方向，可与 ButtonGroup 和 ToggleButtonGroup 组合使用。

import {Bold, Copy, Italic, Scissors, Underline} from "@gravity-ui/icons";
import {
  Button,
  ButtonGroup,
  Separator,

配合 Button Group 使用：

import {
  ArrowUturnCcwLeft,
  ArrowUturnCwRight,
  Bold,
  Italic,

组件改进

ButtonGroup 的增强

新增的 ButtonGroup.Separator 子组件可在按钮之间显式插入一条视觉分隔线。在水平和垂直两种方向下都能正常工作。

import {
  ChevronDown,
  ChevronLeft,
  ChevronRight,
  CodeFork,

Table 与 ListBox 的虚拟化

Table 与 ListBox 现在可以借助 React Aria 的 Virtualizer 来支持大数据集的虚拟化渲染。Virtualizer、TableLayout 和 ListLayout 都已从 @heroui/react 重新导出。

Emma Smith

"use client";

import {Table, TableLayout, Virtualizer} from "@heroui/react";

interface User {

ButtonGroup 的方向

ButtonGroup 现在接受一个 orientation prop（"horizontal" | "vertical"），并在两种方向下都正确处理边框圆角与分隔线方向。根元素也已从 <div> 升级为 React Aria 的 Group，从而具备正确的 role="group" 语义。

横向

纵向

import {TextAlignCenter, TextAlignJustify, TextAlignLeft, TextAlignRight} from "@gravity-ui/icons";
import {Button, ButtonGroup} from "@heroui/react";

export function Orientation() {
  return (

ButtonGroup 的焦点环

成组按钮上的焦点环现在使用 ring-inset，确保焦点环留在按钮内部边界，而不会与相邻按钮重叠。

细粒度的组件引入

@heroui/react 现在支持按组件的子路径入口，方便更明确地按需引入（#6301）：

// Before — root entrypoint
import { Button } from "@heroui/react";

// After — granular subpath import
import { Button } from "@heroui/react/button";

依赖更新

将 react-aria-components 从 v1.15.1 升级到 v1.16.0，同时升级了相关包：

包名	旧版本	新版本
`react-aria-components`	1.15.1	1.16.0
`@react-aria/i18n`	3.12.15	3.12.16
`@react-aria/utils`	3.33.0	3.33.1
`@react-types/shared`	3.33.0	3.33.1
`@react-types/color`	3.1.3	3.1.4
`@internationalized/date`	3.11.0	3.12.0
`@react-stately/data`	3.15.1	3.15.2

Bug 修复

InputGroup：聚焦样式现在仅在实际的 input / textarea 获得焦点时（:has([data-slot]:focus)）才会触发，不再因 :focus-within 而被任意可聚焦的子元素触发（#6274）
Avatar：fallback 元素现在会从父级继承 border-radius，而不再硬编码为 rounded-full，因此 className 覆盖能够正确生效（#6300）
Modal 与 AlertDialog：背景遮罩的点击事件不会再透过 portal 传播到父级元素（#6297）
Table：修复了 Firefox 中表头圆角与背景色溢出的问题（#6298）

链接

贡献者

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

W@wingkwong D@diegonzs J@jrgarciadev

v3.0.0-rc.1

安装