base-ui-react

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Base UI React

Package:

@base-ui/react

v1.2.0 Status: Stable (production-ready) React: 19+ Components: 36+

包:

@base-ui/react

v1.2.0 状态: 稳定（可用于生产环境） React: 19+ 组件数量: 36+

Installation

安装

bash

pnpm add @base-ui/react

Required CSS — add to your app root to create a stacking context for portaled components:

css

#root {
  isolation: isolate;
}

bash

pnpm add @base-ui/react

必需的CSS — 添加到应用根节点，为使用portal的组件创建堆叠上下文：

css

#root {
  isolation: isolate;
}

Architecture

架构

Base UI implements a compound component pattern where each component is a namespace with sub-parts. All imports use sub-path format:

tsx

import { Select } from '@base-ui/react/select';
import { Dialog } from '@base-ui/react/dialog';
import { Tooltip } from '@base-ui/react/tooltip';

Base UI采用复合组件模式，每个组件都是一个包含子部件的命名空间。所有导入均使用子路径格式：

tsx

import { Select } from '@base-ui/react/select';
import { Dialog } from '@base-ui/react/dialog';
import { Tooltip } from '@base-ui/react/tooltip';

Three Render Patterns

三种渲染模式

Every component supports three ways to control its rendered output:

1. Direct Children (Default) — component renders its default HTML element:

tsx

<Dialog.Trigger>Open</Dialog.Trigger>

2. Render Element — pass a JSX element to the

render

prop:

tsx

<Dialog.Trigger render={<a href="#">Open</a>} />

3. Render Function — full control via callback receiving

(props, state)

tsx

<Dialog.Trigger render={(props, state) => <MyButton {...props} active={state.open} />} />

Important: Base UI uses the
render
prop. Never use
asChild
— that is a Radix UI concept and does not exist in Base UI.

每个组件支持三种方式控制其渲染输出：

1. 直接子元素（默认） — 组件渲染其默认HTML元素：

tsx

<Dialog.Trigger>打开</Dialog.Trigger>

2. 渲染元素 — 向

render

属性传递JSX元素：

tsx

<Dialog.Trigger render={<a href="#">打开</a>} />

3. 渲染函数 — 通过接收

(props, state)

的回调实现完全控制：

tsx

<Dialog.Trigger render={(props, state) => <MyButton {...props} active={state.open} />} />

重要提示: Base UI使用
render
属性。请勿使用
asChild
— 这是Radix UI的概念，Base UI中不存在该属性。

Floating Components: Portal > Positioner > Popup

浮动组件：Portal > Positioner > Popup

Components like Select, Popover, Tooltip, Menu, Combobox all use the same three-layer nesting pattern for positioned overlays:

tsx

<Component.Portal>        {/* Renders into document.body */}
  <Component.Positioner>  {/* Handles positioning relative to anchor */}
    <Component.Popup>     {/* The visible floating element */}
      {/* content */}
    </Component.Popup>
  </Component.Positioner>
</Component.Portal>

Never skip

Portal

Positioner

— the positioning system depends on this structure.

Positioner props:

side

align

sideOffset

alignOffset

collisionAvoidance

collisionPadding

CSS variables available on Positioner for sizing:

```
--anchor-width
```
,
```
--anchor-height
```
```
--available-width
```
,
```
--available-height
```
```
--transform-origin
```

Select、Popover、Tooltip、Menu、Combobox等组件均使用相同的三层嵌套模式来实现定位遮罩：

tsx

<Component.Portal>        {/* 渲染到document.body中 */}
  <Component.Positioner>  {/* 处理相对于锚点的定位 */}
    <Component.Popup>     {/* 可见的浮动元素 */}
      {/* 内容 */}
    </Component.Popup>
  </Component.Positioner>
</Component.Portal>

请勿省略

Portal

或

Positioner

— 定位系统依赖此结构。

Positioner属性:

side

align

sideOffset

alignOffset

collisionAvoidance

collisionPadding

Positioner上可用的CSS变量（用于尺寸控制）：

```
--anchor-width
```
,
```
--anchor-height
```
```
--available-width
```
,
```
--available-height
```
```
--transform-origin
```

Styling with Data Attributes

使用数据属性进行样式设置

Base UI exposes component state via data attributes instead of className toggles:

Attribute	Meaning
`[data-popup-open]`	Floating element is visible
`[data-active]`	Tab/item is active
`[data-highlighted]`	Item has keyboard/mouse focus
`[data-checked]`	Checkbox/radio/switch is checked
`[data-unchecked]`	Checkbox/radio/switch is unchecked
`[data-disabled]`	Component is disabled
`[data-required]`	Field is required
`[data-valid]`	Field passes validation
`[data-invalid]`	Field fails validation
`[data-dirty]`	Field value has changed
`[data-touched]`	Field has been focused and blurred
`[data-side="top	right
`[data-align="start	center

Base UI通过数据属性而非className切换来暴露组件状态：

属性	含义
`[data-popup-open]`	浮动元素可见
`[data-active]`	标签页/项处于激活状态
`[data-highlighted]`	项获得键盘/鼠标焦点
`[data-checked]`	复选框/单选框/开关已勾选
`[data-unchecked]`	复选框/单选框/开关未勾选
`[data-disabled]`	组件已禁用
`[data-required]`	字段为必填项
`[data-valid]`	字段验证通过
`[data-invalid]`	字段验证失败
`[data-dirty]`	字段值已更改
`[data-touched]`	字段已被聚焦并失焦
`[data-side="top	right
`[data-align="start	center

Animations

动画

Use

[data-starting-style]

and

[data-ending-style]

for enter/exit transitions:

css

.popup {
  opacity: 1;
  transform: translateY(0);
  transition: opacity 200ms, transform 200ms;
}

.popup[data-starting-style],
.popup[data-ending-style] {
  opacity: 0;
  transform: translateY(-8px);
}

使用

[data-starting-style]

和

[data-ending-style]

实现进入/退出过渡效果：

css

.popup {
  opacity: 1;
  transform: translateY(0);
  transition: opacity 200ms, transform 200ms;
}

.popup[data-starting-style],
.popup[data-ending-style] {
  opacity: 0;
  transform: translateY(-8px);
}

Component Categories

组件分类

Components are organized into four categories. For detailed API, props, and examples, see the corresponding reference file.

组件分为四大类。如需详细API、属性和示例，请查看对应的参考文档。

Floating Components

浮动组件

→ See

references/floating-components.md

Select, Popover, Tooltip, Menu, Menubar, ContextMenu, Combobox, PreviewCard

→ 查看

references/floating-components.md

Select、Popover、Tooltip、Menu、Menubar、ContextMenu、Combobox、PreviewCard

Overlay Components

遮罩组件

→ See

references/overlay-components.md

Dialog, AlertDialog, Drawer

→ 查看

references/overlay-components.md

Dialog、AlertDialog、Drawer

Form Components

表单组件

→ See

references/form-components.md

Field, Fieldset, Form, Input, Checkbox, Radio, NumberField, Slider, Switch, Toggle

→ 查看

references/form-components.md

Field、Fieldset、Form、Input、Checkbox、Radio、NumberField、Slider、Switch、Toggle

Display Components

展示组件

→ See

references/display-components.md

Accordion, Avatar, Button, Tabs, Toast, Toolbar, Progress, ScrollArea, Separator, ToggleGroup, Collapsible

→ 查看

references/display-components.md

Accordion、Avatar、Button、Tabs、Toast、Toolbar、Progress、ScrollArea、Separator、ToggleGroup、Collapsible

Utilities

工具函数

→ See

references/utilities.md

mergeProps, useRender, CSPProvider, DirectionProvider

→ 查看

references/utilities.md

mergeProps、useRender、CSPProvider、DirectionProvider

Critical Rules

关键规则

Always

必须遵守

Use
```
Portal > Positioner > Popup
```
for floating components
Add
```
isolation: isolate
```
to root CSS
Use
```
align
```
prop (not
```
alignment
```
)
Use
```
Select.Item
```
+
```
Select.ItemText
```
(not
```
Option
```
)
Use
```
[data-active]
```
for Tabs (not
```
[data-selected]
```
)
Use
```
mergeProps
```
when combining multiple prop objects
Import from sub-paths:
```
'@base-ui/react/component-name'
```

Place

delay

closeDelay

Tooltip.Trigger

, not

Tooltip.Root

Wrap app in
```
Tooltip.Provider
```
for shared tooltip defaults

浮动组件使用
```
Portal > Positioner > Popup
```
结构
为根节点CSS添加
```
isolation: isolate
```
使用
```
align
```
属性（而非
```
alignment
```
）
使用
```
Select.Item
```
+
```
Select.ItemText
```
（而非
```
Option
```
）
标签页使用
```
[data-active]
```
（而非
```
[data-selected]
```
）
合并多个属性对象时使用
```
mergeProps
```
从子路径导入：
```
'@base-ui/react/component-name'
```

将

delay

closeDelay

设置在

Tooltip.Trigger

上，而非

Tooltip.Root

使用
```
Tooltip.Provider
```
包裹应用以设置全局tooltip默认值

Never

禁止操作

Use
```
asChild
```
— Base UI uses
```
render
```
prop instead
Skip
```
Portal
```
or
```
Positioner
```
for floating components
Use Radix UI naming conventions (they differ)
Assume Accordion allows multiple panels by default (
```
multiple
```
defaults to
```
false
```
)
Place tooltip timing props on Root instead of Trigger

请勿使用
```
asChild
```
— Base UI使用
```
render
```
属性替代
浮动组件请勿省略
```
Portal
```
或
```
Positioner
```
请勿使用Radix UI的命名约定（两者存在差异）
请勿默认认为Accordion允许多个面板展开（
```
multiple
```
默认值为
```
false
```
）
请勿将tooltip的计时属性设置在Root上，而应设置在Trigger上