v3.0.0-beta.3

七个新组件、fullWidth 与 hideSeparator 支持、样式修复，以及 AlertDialog / Modal backdrop 变体调整与移除 asChild prop 等破坏性变更。

2025 年 12 月 19 日

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

安装

升级到最新版本：

1npm i @lenso/tokens@beta @lenso/ui@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

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// Adapted from HeroUI v3.2.6 (e385ac2), Apache-2.0.3import {4  ChevronDown,5  ChevronLeft,6  ChevronRight,7  CodeFork,8  Ellipsis,9  Picture,10  Pin,11  QrCode,12  Star,13  TextAlignCenter,14  TextAlignJustify,15  TextAlignLeft,16  TextAlignRight,17  ThumbsDown,18  ThumbsUp,19  Video,20} from "@gravity-ui/icons";21import { Button, ButtonGroup, Chip, Dropdown } from "@lenso/ui";22import * as stylex from "@stylexjs/stylex";23import { basicStyles as styles } from "./basic.stylex";24import { styles as sourceStyles } from "./source.stylex";25export function Basic() {26  return (27    <div {...stylex.props(styles.root)}>28      <div {...stylex.props(styles.section)}>29        <ButtonGroup>30          <Button>Merge pull request</Button>31          <Dropdown>32            <Dropdown.Trigger33              render={<Button isIconOnly aria-label="More options" xstyle={styles.splitTrigger} />}34            >35              <ButtonGroup.Separator />36              <Button.Icon>37                <ChevronDown />38              </Button.Icon>39            </Dropdown.Trigger>40            <Dropdown.Portal>41              <Dropdown.Positioner side="bottom" align="end">42                <Dropdown.Popup xstyle={styles.popup}>43                  {[44                    {45                      id: "merge",46                      label: "Create a merge commit",47                      description: "All commits from this branch will be added to the base branch",48                    },49                    {50                      id: "squash",51                      label: "Squash and merge",52                      description:53                        "The 14 commits from this branch will be combined into one commit in the base branch",54                    },55                    {56                      id: "rebase",57                      label: "Rebase and merge",58                      description:59                        "The 14 commits from this branch will be rebased and added to the base branch",60                    },61                  ].map((item) => (62                    <Dropdown.Item key={item.id} xstyle={styles.item}>63                      <span {...stylex.props(sourceStyles.menuLabel)}>{item.label}</span>64                      <span {...stylex.props(sourceStyles.menuDescription)}>65                        {item.description}66                      </span>67                    </Dropdown.Item>68                  ))}69                </Dropdown.Popup>70              </Dropdown.Positioner>71            </Dropdown.Portal>72          </Dropdown>73        </ButtonGroup>74      </div>75      <div {...stylex.props(styles.section)}>76        <div {...stylex.props(styles.row)}>77          <ButtonGroup variant="tertiary">78            <Button>79              <CodeFork {...stylex.props(styles.smallIcon)} />80              Fork81              <Chip color="accent" size="sm" variant="soft">82                2483              </Chip>84            </Button>85            <Button isIconOnly aria-label="More fork options">86              <ButtonGroup.Separator />87              <Button.Icon>88                <ChevronDown />89              </Button.Icon>90            </Button>91          </ButtonGroup>92          <ButtonGroup variant="tertiary">93            <Button isIconOnly aria-label="Show QR code">94              <Button.Icon>95                <QrCode />96              </Button.Icon>97            </Button>98            <Button>99              <ButtonGroup.Separator />100              Scan to pay101            </Button>102          </ButtonGroup>103          <ButtonGroup variant="tertiary">104            <Button>105              <Button.Icon>106                <ThumbsUp />107              </Button.Icon>108              <span {...stylex.props(styles.count)}>2.4K</span>109            </Button>110            <Button isIconOnly aria-label="Dislike">111              <ButtonGroup.Separator />112              <Button.Icon>113                <ThumbsDown />114              </Button.Icon>115            </Button>116          </ButtonGroup>117          <ButtonGroup variant="tertiary">118            <Button>119              <Star {...stylex.props(styles.smallIcon)} />120              Star121            </Button>122            <Button xstyle={styles.countButton}>123              <ButtonGroup.Separator />124              <Chip color="accent" size="sm" variant="soft">125                104126              </Chip>127            </Button>128          </ButtonGroup>129          <ButtonGroup variant="tertiary">130            <Button>131              <Button.Icon>132                <Pin />133              </Button.Icon>134              Pinned135            </Button>136            <Button isIconOnly aria-label="More pin options">137              <ButtonGroup.Separator />138              <Button.Icon>139                <ChevronDown />140              </Button.Icon>141            </Button>142          </ButtonGroup>143        </div>144      </div>145      <div {...stylex.props(styles.section)}>146        <ButtonGroup variant="tertiary">147          <Button>148            <Button.Icon>149              <ChevronLeft />150            </Button.Icon>151            Previous152          </Button>153          <Button>154            <ButtonGroup.Separator />155            Next156            <Button.Icon>157              <ChevronRight />158            </Button.Icon>159          </Button>160        </ButtonGroup>161      </div>162      <div {...stylex.props(styles.section)}>163        <ButtonGroup variant="tertiary">164          <Button>165            <Button.Icon>166              <Picture />167            </Button.Icon>168            Photos169          </Button>170          <Button>171            <ButtonGroup.Separator />172            <Button.Icon>173              <Video />174            </Button.Icon>175            Videos176          </Button>177          <Button isIconOnly aria-label="More options">178            <ButtonGroup.Separator />179            <Button.Icon>180              <Ellipsis />181            </Button.Icon>182          </Button>183        </ButtonGroup>184      </div>185      <div {...stylex.props(styles.section)}>186        <ButtonGroup variant="tertiary">187          <Button>Left</Button>188          <Button>189            <ButtonGroup.Separator />190            Center191          </Button>192          <Button>193            <ButtonGroup.Separator />194            Right195          </Button>196        </ButtonGroup>197      </div>198      <div {...stylex.props(styles.section)}>199        <ButtonGroup variant="tertiary">200          {[201            { label: "Align left", icon: <TextAlignLeft /> },202            { label: "Align center", icon: <TextAlignCenter /> },203            { label: "Align right", icon: <TextAlignRight /> },204            { label: "Justify", icon: <TextAlignJustify /> },205          ].map((item, index) => (206            <Button key={item.label} isIconOnly aria-label={item.label}>207              {index > 0 && <ButtonGroup.Separator />}208              <Button.Icon>{item.icon}</Button.Icon>209            </Button>210          ))}211        </ButtonGroup>212      </div>213    </div>214  );215}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

DateField

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2
3// HeroUI v3.2.6. Copyright NextUI Inc. SPDX-License-Identifier: Apache-2.0.4import { DateField } from "@lenso/ui";5import { styles } from "./demo-styles";6
7export function Basic() {8  return (9    <DateField xstyle={styles.field} name="date">10      <DateField.Label>Date</DateField.Label>11      <DateField.Group>12        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>13      </DateField.Group>14    </DateField>15  );16}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

ErrorMessage

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// Adapted from HeroUI v3.2.6, e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e, Apache-2.0.3import { Description, ErrorMessage, Label, Tag, TagGroup } from "@lenso/ui";4import type { TagGroupRootProps } from "@lenso/ui";5import { useId, useState } from "react";6
7const categories = ["News", "Travel", "Gaming", "Shopping"];8export function ErrorMessageBasic() {9  const [selected, setSelected] = useState<TagGroupRootProps["selectedKeys"]>(new Set());10  const labelId = useId();11  const descriptionId = useId();12  const errorId = useId();13  const invalid = !selected || selected.size === 0;14  return (15    <TagGroup16      selectedKeys={selected}17      selectionMode="multiple"18      onSelectionChange={setSelected}19      aria-labelledby={labelId}20      aria-describedby={`${descriptionId}${invalid ? ` ${errorId}` : ""}`}21      aria-invalid={invalid}22    >23      <Label id={labelId} nativeLabel={false}>24        Required Categories25      </Label>26      <TagGroup.List>27        {categories.map((category) => (28          <Tag key={category} itemKey={category.toLowerCase()} textValue={category}>29            {category}30          </Tag>31        ))}32      </TagGroup.List>33      <Description id={descriptionId}>Select at least one category</Description>34      <ErrorMessage id={errorId}>35        {invalid && <>Please select at least one category</>}36      </ErrorMessage>37    </TagGroup>38  );39}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

SearchField

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2
3// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.4import { Label, SearchField } from "@lenso/ui";5import * as stylex from "@stylexjs/stylex";6const styles = stylex.create({ input: { width: 280 } });7
8export function Basic() {9  return (10    <SearchField name="search">11      <Label>Search</Label>12      <SearchField.Group>13        <SearchField.SearchIcon />14        <SearchField.Input xstyle={styles.input} placeholder="Search..." />15        <SearchField.ClearButton />16      </SearchField.Group>17    </SearchField>18  );19}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

ScrollShadow

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// Adapted from HeroUI v3.2.6 (Apache-2.0).3import { Card, ScrollShadow } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const images = [6  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/robot1.jpeg",7  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg",8  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oranges.jpeg",9];10const styles = stylex.create({11  root: { width: "100%", maxWidth: { default: null, "@media (min-width: 640px)": 384 } },12  vertical: { marginBottom: 32, width: "100%" },13  heading: { marginBottom: 8, fontSize: 14, lineHeight: "20px", fontWeight: 600 },14  card: { width: "100%", padding: 0 },15  verticalScroll: { maxHeight: 240, padding: 16 },16  horizontalScroll: { padding: 16 },17  paragraphs: { display: "flex", flexDirection: "column", gap: 16 },18  cards: { display: "flex", flexDirection: "row", gap: 16 },19  item: { display: "flex", minWidth: 200, flexDirection: "row", gap: 12, padding: 4 },20  image: {21    aspectRatio: "1",22    width: { default: 64, "@media (min-width: 640px)": 80 },23    height: { default: 64, "@media (min-width: 640px)": 80 },24    flexShrink: 0,25    borderRadius: "var(--radius-xl)",26    objectFit: "cover",27    userSelect: "none",28  },29  text: { display: "flex", flex: 1, flexDirection: "column", justifyContent: "center", gap: 4 },30  title: { fontSize: 14 },31  description: { fontSize: 12 },32});33export default function Orientation() {34  return (35    <div {...stylex.props(styles.root)}>36      <div {...stylex.props(styles.vertical)}>37        <h4 {...stylex.props(styles.heading)}>Vertical</h4>38        <Card xstyle={styles.card}>39          <ScrollShadow40            tabIndex={0}41            aria-label="Vertical sample"42            xstyle={styles.verticalScroll}43            orientation="vertical"44          >45            <div {...stylex.props(styles.paragraphs)}>46              {Array.from({ length: 10 }, (_, index) => (47                <p key={index}>48                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non49                  risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor50                  quam. Morbi accumsan cursus enim, sed ultricies sapien.51                </p>52              ))}53            </div>54          </ScrollShadow>55        </Card>56      </div>57      <div>58        <h4 {...stylex.props(styles.heading)}>Horizontal</h4>59        <Card xstyle={styles.card}>60          <ScrollShadow61            tabIndex={0}62            aria-label="Horizontal cards"63            xstyle={styles.horizontalScroll}64            orientation="horizontal"65          >66            <div {...stylex.props(styles.cards)}>67              {Array.from({ length: 10 }, (_, index) => (68                <Card key={index} xstyle={styles.item} variant="transparent">69                  <img70                    alt="Lorem Card"71                    {...stylex.props(styles.image)}72                    loading="lazy"73                    src={images[index % images.length]}74                  />75                  <div {...stylex.props(styles.text)}>76                    <Card.Title xstyle={styles.title}>Bridging the Future</Card.Title>77                    <Card.Description xstyle={styles.description}>Today, 6:30 PM</Card.Description>78                  </div>79                </Card>80              ))}81            </div>82          </ScrollShadow>83        </Card>84      </div>85    </div>86  );87}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2
3// Adapted from HeroUI v3.2.6 tag-group-basic (Apache-2.0).4import { PlanetEarth, Rocket, ShoppingBag, SquareArticle } from "@gravity-ui/icons";5import { Tag, TagGroup } from "@lenso/ui";6
7export function TagGroupBasic() {8  return (9    <TagGroup aria-label="Tags" selectionMode="single">10      <TagGroup.List>11        <Tag itemKey="default-news" textValue="News">12          <SquareArticle width={12} height={12} />13          News14        </Tag>15        <Tag itemKey="default-travel" textValue="Travel">16          <PlanetEarth width={12} height={12} />17          Travel18        </Tag>19        <Tag itemKey="default-gaming" textValue="Gaming">20          <Rocket width={12} height={12} />21          Gaming22        </Tag>23        <Tag itemKey="default-shopping" textValue="Shopping">24          <ShoppingBag width={12} height={12} />25          Shopping26        </Tag>27      </TagGroup.List>28    </TagGroup>29  );30}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

TimeField

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2
3// HeroUI v3.2.6. Copyright NextUI Inc. SPDX-License-Identifier: Apache-2.0.4import { TimeField } from "@lenso/ui";5import { styles } from "../date-field/demo-styles";6
7export function Basic() {8  return (9    <TimeField xstyle={styles.field} name="time">10      <TimeField.Label>Time</TimeField.Label>11      <TimeField.Group>12        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>13      </TimeField.Group>14    </TimeField>15  );16}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

全宽支持

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

支持的组件：

组件改进

分隔线控制增强

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

Tabs：

1<Tabs hideSeparator>2  <Tabs.ListContainer>3    <Tabs.List aria-label="Options">4      <Tabs.Tab id="overview">Overview<Tabs.Indicator /></Tabs.Tab>5      <Tabs.Tab id="analytics">Analytics<Tabs.Indicator /></Tabs.Tab>6    </Tabs.List>7  </Tabs.ListContainer>8</Tabs>

ButtonGroup：

1<ButtonGroup hideSeparator>2  <Button>First</Button>3  <Button>Second</Button>4  <Button>Third</Button>5</ButtonGroup>

Accordion：

1<Accordion hideSeparator>2  <Accordion.Item>3    <Accordion.Heading>4      <Accordion.Trigger>Item 1</Accordion.Trigger>5    </Accordion.Heading>6    <Accordion.Panel>7      <Accordion.Body>Content</Accordion.Body>8    </Accordion.Panel>9  </Accordion.Item>10</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"：

1// Before2<AlertDialog.Backdrop backdropVariant="solid">3  <AlertDialog.Container>4    {/* content */}5  </AlertDialog.Container>6</AlertDialog.Backdrop>7
8<Modal.Backdrop variant="solid">9  <Modal.Container>10    {/* content */}11  </Modal.Container>12</Modal.Backdrop>13
14// After15<AlertDialog.Backdrop backdropVariant="opaque">16  <AlertDialog.Container>17    {/* content */}18  </AlertDialog.Container>19</AlertDialog.Backdrop>20
21<Modal.Backdrop variant="opaque">22  <Modal.Container>23    {/* content */}24  </Modal.Container>25</Modal.Backdrop>

可用的 backdrop 变体：

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

移除 `asChild` prop

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

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

Bug 修复

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

链接

贡献者

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

HeroUI contributors