v3.0.0-beta.2

六个新组件（AlertDialog、ComboBox、Dropdown、InputGroup、Modal、NumberField）、Select API 改进以及多项组件优化。

2025 年 11 月 20 日

此版本引入了六个重要的新组件，改进了 Select 组件的 API，并包含多项优化与 bug 修复。

安装

升级到最新版本：

1npm i @lenso/tokens@beta @lenso/ui@beta

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

新增功能

新组件

本次发布引入了 6 个 新的基础组件：

AlertDialog：用于需要用户确认的重要决策的模态对话框。（文档）
ComboBox：将文本输入与列表框结合，让用户可以在选项列表中过滤。（文档）
Dropdown：展示一组可供用户选择的操作或选项。（文档）
InputGroup：通过 prefix 与 suffix 元素将相关输入控件组合在一起，强化表单字段。（文档）
Modal：用于聚焦用户交互与重要内容的对话框浮层。（文档）
NumberField：数字输入框，带有递增 / 递减按钮、表单校验以及国际化格式化。（文档）

AlertDialog

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

1"use client";2
3// Adapted from HeroUI v3.2.6 alert-dialog-default (Apache-2.0).4import * as stylex from "@stylexjs/stylex";5import { AlertDialog, Button } from "@lenso/ui";6
7const styles = stylex.create({ popup: { maxWidth: 400 } });8
9export function Default() {10  return (11    <AlertDialog>12      <AlertDialog.Trigger render={<Button variant="danger" />}>Delete Project</AlertDialog.Trigger>13      <AlertDialog.Portal>14        <AlertDialog.Backdrop />15        <AlertDialog.Viewport>16          <AlertDialog.Popup xstyle={styles.popup}>17            <AlertDialog.Close aria-label="Close dialog" />18            <AlertDialog.Header>19              <AlertDialog.Icon variant="danger" />20              <AlertDialog.Title>Delete project permanently?</AlertDialog.Title>21            </AlertDialog.Header>22            <AlertDialog.Body>23              <AlertDialog.Description>24                This will permanently delete <strong>My Awesome Project</strong> and all of its25                data. This action cannot be undone.26              </AlertDialog.Description>27            </AlertDialog.Body>28            <AlertDialog.Footer>29              <AlertDialog.Close render={<Button variant="tertiary" />}>Cancel</AlertDialog.Close>30              <AlertDialog.Close render={<Button variant="danger" />}>31                Delete Project32              </AlertDialog.Close>33            </AlertDialog.Footer>34          </AlertDialog.Popup>35        </AlertDialog.Viewport>36      </AlertDialog.Portal>37    </AlertDialog>38  );39}

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

ComboBox

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

1"use client";2// HeroUI v3.2.6, Apache-2.0. Native Base UI adaptation.3import { AnimalPicker } from "./shared";4export function Default() {5  return <AnimalPicker />;6}

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

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

1"use client";2
3// Adapted from HeroUI v3.2.6 dropdown-default (Apache-2.0).4import { Button, Dropdown } from "@lenso/ui";5import { ActionItem, Popup } from "./_shared";6
7export function Default() {8  return (9    <Dropdown>10      <Dropdown.Trigger render={<Button aria-label="Menu" variant="secondary" />}>11        Actions12      </Dropdown.Trigger>13      <Popup>14        <ActionItem label="New file" onClick={() => console.log("Selected: new-file")} />15        <ActionItem label="Copy link" onClick={() => console.log("Selected: copy-link")} />16        <ActionItem label="Edit file" onClick={() => console.log("Selected: edit-file")} />17        <ActionItem18          label="Delete file"19          variant="danger"20          onClick={() => console.log("Selected: delete-file")}21        />22      </Popup>23    </Dropdown>24  );25}

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

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

1"use client";2
3// Adapted from HeroUI v3.2.6 modal-default (Apache-2.0).4import { Rocket } from "@gravity-ui/icons";5import * as stylex from "@stylexjs/stylex";6import { Button, Modal } from "@lenso/ui";7
8const styles = stylex.create({9  popup: { maxWidth: 360 },10  icon: { backgroundColor: "var(--default)", color: "var(--foreground)" },11  rocket: { width: 20, height: 20 },12  continue: { width: "100%" },13});14
15export function Default() {16  return (17    <Modal>18      <Modal.Trigger render={<Button variant="secondary" />}>Open Modal</Modal.Trigger>19      <Modal.Portal>20        <Modal.Backdrop />21        <Modal.Viewport>22          <Modal.Popup xstyle={styles.popup}>23            <Modal.Close aria-label="Close dialog" />24            <Modal.Header>25              <Modal.Icon xstyle={styles.icon}>26                <Rocket {...stylex.props(styles.rocket)} />27              </Modal.Icon>28              <Modal.Title>Welcome to HeroUI</Modal.Title>29            </Modal.Header>30            <Modal.Body>31              <Modal.Description>32                A beautiful, fast, and modern React UI library for building accessible and33                customizable web applications with ease.34              </Modal.Description>35            </Modal.Body>36            <Modal.Footer>37              <Modal.Close render={<Button xstyle={styles.continue} />}>Continue</Modal.Close>38            </Modal.Footer>39          </Modal.Popup>40        </Modal.Viewport>41      </Modal.Portal>42    </Modal>43  );44}

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

InputGroup

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

1"use client";2// Adapted from HeroUI v3.2.6, Apache-2.0.3import { Globe } from "@gravity-ui/icons";4import { InputGroup, Label, TextField } from "@lenso/ui";5import * as stylex from "@stylexjs/stylex";6const styles = stylex.create({7  field: { width: "100%", maxWidth: 280 },8  icon: { width: 16, height: 16, color: "var(--muted)" },9});10export function WithIconPrefixAndTextSuffix() {11  return (12    <TextField xstyle={styles.field} name="website">13      <Label>Website</Label>14      <InputGroup>15        <InputGroup.Prefix>16          <Globe aria-hidden="true" {...stylex.props(styles.icon)} />17        </InputGroup.Prefix>18        <InputGroup.Input xstyle={styles.field} defaultValue="heroui" />19        <InputGroup.Suffix>.com</InputGroup.Suffix>20      </InputGroup>21    </TextField>22  );23}

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

NumberField

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

1"use client";2
3// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.4import { Label, NumberField, TextField } from "@lenso/ui";5import { Controls, styles } from "./parts";6
7export function Basic() {8  return (9    <TextField name="width" xstyle={styles.field}>10      <NumberField defaultValue={1024} min={0} name="width">11        <Label>Width</Label>12        <Controls />13      </NumberField>14    </TextField>15  );16}

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

样式改进

自定义变体与主题兼容性

增强了 CSS 变体与主题系统，提供更好的可定制性：

动效偏好：

新增 motion-safe 变体，可与 data-reduce-motion="true" 属性配合使用
增强后的 motion-reduce 现在支持祖先元素与伪元素

深色模式：

类与 data-theme="dark" 属性选择器现在优先于 prefers-color-scheme
在深色模式下完整支持伪元素

主题变量：

扩展了浅色主题的覆盖范围，以支持嵌套主题（:root、.light、.default、[data-theme="light"]、[data-theme="default"]）

组件改进

Select 组件 API 更新

Select 组件的 API 已经过改进，与其他组件保持一致。Content 子组件已重命名为 Popover。

之前：

1<Select>2  <Select.Trigger>3    <Select.Value />4    <Select.Indicator />5  </Select.Trigger>6  <Select.Content>7    <ListBox>8      {/* items */}9    </ListBox>10  </Select.Content>11</Select>

之后：

1<Select>2  <Select.Trigger>3    <Select.Value />4    <Select.Indicator />5  </Select.Trigger>6  <Select.Popover>7    <ListBox>8      {/* items */}9    </ListBox>10  </Select.Popover>11</Select>

Chip 组件改进

Chip 组件的尺寸已更新，以提升一致性：

小（sm）：px-1 py-0 text-xs
中（md）：text-xs（现在显式设置）
大（lg）：px-3 py-1 text-sm font-medium

Separator 组件增强

Separator 组件现在能自动检测是否被放置在 surface 组件中（使用 bg-surface），并应用合适的分隔线颜色以获得更好的可见性。同时新增了 isOnSurface prop，用于手动控制。

新增的计算变量：

--color-separator-on-surface：通过 color-mix 自动生成的计算变量，确保分隔线在 surface 背景上仍然清晰可见。与其他计算变量一样，可在你的主题中覆盖它。

用法：

1<div className="bg-surface">2  <Separator isOnSurface />3</div>

当 Separator 检测到外层存在 SurfaceContext Provider（由 Card、Alert、Popover、Modal 等组件提供）时，isOnSurface prop 会自动启用。

你也可以直接在 Tailwind 类中使用这个计算变量：

1<div className="bg-surface">2  <div className="h-px w-full bg-separator-on-surface" />3</div>

动画改进

更新了加载状态 spinner 的颜色，提升可见性
调整了 Select 与 Slider 组件的样式，改进动画效果
改进了 Checkbox 动画（过渡更快）
在伪元素中更好地支持 prefers-reduced-motion

⚠️ 破坏性变更

Select 组件

为与 ComboBox、Dropdown 等组件保持一致，Select.Content 子组件已重命名为 Select.Popover。

迁移：

将所有 Select.Content 替换为 Select.Popover：

1// Before2<Select.Content>3  <ListBox>...</ListBox>4</Select.Content>5
6// After7<Select.Popover>8  <ListBox>...</ListBox>9</Select.Popover>

类型导入：

1// Before2import type { SelectContentProps } from "@lenso/ui"3
4// After5import type { SelectPopoverProps } from "@lenso/ui"

命名导出：

1// Before2import { SelectContent } from "@lenso/ui"3
4// After5import { SelectPopover } from "@lenso/ui"

CSS 变量与工具类：divider → separator

为与 Separator 组件名保持一致，所有与 divider 相关的 CSS 变量与工具类均已重命名为 separator。

CSS 变量：

1/* Before */2border-bottom: 1px solid var(--divider);3
4/* After */5border-bottom: 1px solid var(--separator);

Tailwind 工具类：

1// Before2<div className="bg-divider" />3<div className="border-divider" />4
5// After6<div className="bg-separator" />7<div className="border-separator" />

主题覆盖：

如果你的自定义主题中覆盖了 separator 相关变量，请同步更新：

1/* Before */2:root {3  --divider: oklch(92% 0.004 286.32);4}5
6.dark {7  --divider: oklch(22% 0.006 286.033);8}9
10/* After */11:root {12  --separator: oklch(92% 0.004 286.32);13}14
15.dark {16  --separator: oklch(22% 0.006 286.033);17}

Bug 修复

修复了加载状态 spinner 的颜色，提升可见性
修复了 bordered 状态下焦点样式优先于 hover 状态的表现
修复了文档中的动画卡顿问题
改进了模态表单的样式
增强了 motion-reduce 在伪元素上的支持
修复了移动端触摸交互后悬停状态保留的问题——将 hover 样式包裹在 @media (hover: hover) 媒体查询中。同时通过移除不必要的 ="true" data 属性值选择器，简化了相关代码。

链接

贡献者

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

HeroUI contributors