base-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Base UI (React)

Base UI provides unstyled, composable React components. This skill focuses on assembling multi-part components, composing with the

render

prop, and meeting accessibility requirements while you supply styling.

Base UI 提供无样式、可组合的 React 组件。本技能聚焦于组装多部分组件、使用

render

prop进行组件组合，以及在你自定义样式的同时满足无障碍访问要求。

When to use

使用场景

Use this skill when the user wants to:

Build UI with
```
@base-ui/react
```
primitives.
Compose unstyled components with custom markup and styling.
Implement menus, overlays, toasts, and toolbars.
Build accessible form controls and grouped inputs.

当用户有以下需求时，可使用本技能：

使用
```
@base-ui/react
```
基础组件构建UI。
通过自定义标记和样式组合无样式组件。
实现菜单、浮层、提示框（Toast）和工具栏。
构建符合无障碍标准的表单控件和分组输入框。

Quick navigation (references)

快速导航（参考文档）

Utilities

工具类

references/csp-provider.md
references/direction-provider.md
references/merge-props.md
references/use-render.md

references/csp-provider.md
references/direction-provider.md
references/merge-props.md
references/use-render.md

Forms & inputs

表单与输入框

references/form.md
references/fieldset.md
references/input.md
references/number-field.md
references/radio.md
references/select.md
references/slider.md
references/switch.md

references/form.md
references/fieldset.md
references/input.md
references/number-field.md
references/radio.md
references/select.md
references/slider.md
references/switch.md

Feedback & status

反馈与状态

references/meter.md
references/progress.md
references/toast.md

references/meter.md
references/progress.md
references/toast.md

Menus, navigation, overlays

菜单、导航、浮层

references/menu.md
references/menubar.md
references/navigation-menu.md
references/popover.md
references/preview-card.md
references/tooltip.md

references/menu.md
references/menubar.md
references/navigation-menu.md
references/popover.md
references/preview-card.md
references/tooltip.md

Toggles & controls

开关与控件

references/toggle.md
references/toggle-group.md
references/toolbar.md

references/toggle.md
references/toggle-group.md
references/toolbar.md

Layout & separators

布局与分隔符

references/scroll-area.md
references/separator.md

references/scroll-area.md
references/separator.md

Core concepts to apply

核心概念

Unstyled primitives: all visuals come from your CSS/Tailwind/CSS Modules. Base UI handles behavior and accessibility.
Multi-part anatomy: most components follow
```
Root
```
+ subparts (
```
Trigger
```
,
```
Popup
```
,
```
Item
```
, etc.). Assemble them explicitly.
render
prop: replace the default element or wrap with your own component; when using the function form, merge props manually with
```
mergeProps
```
.

State-driven styling: many parts expose data attributes such as

data-[popup-open]

data-[highlighted]

data-[pressed]

data-[checked]

data-[invalid]

, etc.

Portals for overlays: use
```
Portal
```
+
```
Positioner
```
+
```
Popup
```
for popovers, menus, tooltips, select, navigation menu content, and preview cards.

无样式基础组件：所有视觉样式均来自你的CSS/Tailwind/CSS Modules。Base UI 负责处理组件行为和无障碍访问逻辑。
多部分结构：大多数组件遵循「Root + 子部件（如Trigger、Popup、Item等）」的结构，需要你显式组装。
render
prop：替换默认元素或用自定义组件包裹；当使用函数形式时，需用
```
mergeProps
```
手动合并props。
状态驱动样式：许多部件会暴露数据属性，例如
```
data-[popup-open]
```
、
```
data-[highlighted]
```
、
```
data-[pressed]
```
、
```
data-[checked]
```
、
```
data-[invalid]
```
等。
浮层使用Portal：对于弹出框、菜单、提示框、选择器、导航菜单内容和预览卡片，需结合使用
```
Portal
```
+
```
Positioner
```
+
```
Popup
```
。

Recipes

实践方案

1) Build accessible forms quickly

1) 快速构建无障碍表单

Wrap inputs with
```
Form
```
for submission and error aggregation.

Use

Field.Root

with a

name

, then

Field.Label

Field.Control

, and

Field.Error

for labels and errors.

Group related fields with
```
Fieldset.Root
```
+
```
Fieldset.Legend
```
.

For

Radio

groups, either use

RadioGroup

with

aria-labelledby

, or render

RadioGroup

via

Fieldset.Root

and use

Field.Label

for each option.

Ensure every form control has an accessible name (label or
```
Field
```
/
```
Fieldset
```
labeling pattern).

用
```
Form
```
包裹输入框，处理表单提交和错误聚合。
使用带
```
name
```
属性的
```
Field.Root
```
，搭配
```
Field.Label
```
、
```
Field.Control
```
和
```
Field.Error
```
实现标签和错误提示。
用
```
Fieldset.Root
```
+
```
Fieldset.Legend
```
对相关字段进行分组。
对于
```
Radio
```
组，可使用带
```
aria-labelledby
```
的
```
RadioGroup
```
，或通过
```
Fieldset.Root
```
渲染
```
RadioGroup
```
，并为每个选项使用
```
Field.Label
```
。
确保每个表单控件都有可访问的名称（通过标签或
```
Field
```
/
```
Fieldset
```
标记模式）。

2) Compose with

render

mergeProps

2) 结合

render

mergeProps

进行组件组合

When passing a React element to
```
render
```
, Base UI merges props automatically.
When passing a function to
```
render
```
, merge Base UI props and your props with
```
mergeProps
```
.
Use
```
event.preventBaseUIHandler()
```
inside merged event handlers to stop Base UI’s internal behavior when needed (synthetic events only).

当向
```
render
```
传递React元素时，Base UI会自动合并props。
当向
```
render
```
传递函数时，必须使用
```
mergeProps
```
合并Base UI的props和你的自定义props。
当需要阻止Base UI的内部行为时，可在合并后的事件处理函数中使用
```
event.preventBaseUIHandler()
```
（仅适用于合成事件）。

3) Overlays and menus (portaled UI)

3) 浮层与菜单（使用Portal的UI）

Build popups using
```
Root
```
+
```
Trigger
```
+
```
Portal
```
+
```
Positioner
```
+
```
Popup
```
.
For menus and navigation, add
```
Item
```
,
```
Separator
```
,
```
Arrow
```
, and list/viewport parts as needed.
```
NavigationMenu.Link
```
supports
```
render
```
for framework router links.

结合
```
Root
```
+
```
Trigger
```
+
```
Portal
```
+
```
Positioner
```
+
```
Popup
```
构建弹出框。
对于菜单和导航，按需添加
```
Item
```
、
```
Separator
```
、
```
Arrow
```
以及列表/视口部件。
```
NavigationMenu.Link
```
支持通过
```
render
```
适配框架路由链接。

4) Toasts

4) 提示框（Toast）

Wrap the app (or a subtree) with
```
Toast.Provider
```
.
Use
```
Toast.useToastManager()
```
to create toasts.

Render a

Toast.Viewport

inside

Toast.Portal

, then map

toasts

Toast.Root

entries with

Toast.Content

Toast.Title

Toast.Description

, and

Toast.Close

用
```
Toast.Provider
```
包裹应用（或其子树）。
使用
```
Toast.useToastManager()
```
创建提示框。

在

Toast.Portal

内渲染

Toast.Viewport

，然后将

toasts

映射为包含

Toast.Content

、

Toast.Title

、

Toast.Description

和

Toast.Close

的

Toast.Root

条目。

5) RTL and CSP constraints

5) RTL布局与CSP约束

For RTL behavior, wrap with
```
DirectionProvider
```
and also set
```
dir="rtl"
```
(provider does not set the DOM direction).
For strict CSP, wrap with
```
CSPProvider
```
and pass
```
nonce
```
, or disable inline style elements if your app supplies external styles. Beware inline style attributes are not controlled by
```
CSPProvider
```
.

如需RTL（从右到左）布局，用
```
DirectionProvider
```
包裹组件，同时设置
```
dir="rtl"
```
（Provider不会自动设置DOM的方向属性）。
对于严格的CSP（内容安全策略），用
```
CSPProvider
```
包裹并传入
```
nonce
```
，或在应用使用外部样式时禁用内联样式元素。注意，内联样式属性不受
```
CSPProvider
```
控制。

6) Sliders and ranges

6) 滑块与范围选择器

Single value sliders: one
```
Slider.Thumb
```
.
Range sliders: pass an array and render a
```
Slider.Thumb
```
per value; add
```
index
```
for SSR alignment.
Adjust thumb alignment with
```
thumbAlignment
```
when edge alignment is required.

单值滑块：使用一个
```
Slider.Thumb
```
。
范围滑块：传入数组并为每个值渲染一个
```
Slider.Thumb
```
；为了SSR对齐，需添加
```
index
```
属性。
当需要边缘对齐时，使用
```
thumbAlignment
```
调整滑块的对齐方式。

Critical prohibitions

注意事项

Do not omit accessible labels for inputs, sliders, switches, or radio groups.
Do not expect Base UI to provide default styling; apply your own styles.
Do not forget
```
Portal
```
for overlays that need to escape stacking/overflow contexts.
Do not skip
```
mergeProps
```
when using the function form of
```
render
```
.

不得省略输入框、滑块、开关或单选按钮组的无障碍标签。
不要期望Base UI提供默认样式；需自行应用自定义样式。
对于需要突破堆叠/溢出上下文的浮层，不要忘记使用
```
Portal
```
。
当使用
```
render
```
的函数形式时，不得遗漏
```
mergeProps
```
。

Output expectations

输出要求

When responding to the user, provide:

The specific Base UI components to use (and their key parts).
A brief assembly plan (Root + parts + portal/positioner where relevant).
A short checklist for accessibility and state-driven styling.

回复用户时，需包含：

推荐使用的具体Base UI组件（及其核心部件）。
简短的组装方案（Root + 部件 + 按需使用的portal/positioner）。
无障碍访问和状态驱动样式的简短检查清单。",

base-ui

Original

Translation

Base UI (React)

Base UI (React)

When to use

使用场景

Quick navigation (references)

快速导航（参考文档）

Utilities

工具类

Forms & inputs

表单与输入框

Feedback & status

反馈与状态

Menus, navigation, overlays

菜单、导航、浮层

Toggles & controls

开关与控件

Layout & separators

布局与分隔符

Core concepts to apply

核心概念

Recipes

实践方案

1) Build accessible forms quickly

1) 快速构建无障碍表单

2) Compose with render + mergeProps

2) 结合render + mergeProps进行组件组合

3) Overlays and menus (portaled UI)

3) 浮层与菜单（使用Portal的UI）

4) Toasts

4) 提示框（Toast）

5) RTL and CSP constraints

5) RTL布局与CSP约束

6) Sliders and ranges

6) 滑块与范围选择器

Critical prohibitions

注意事项

Output expectations

输出要求

2) Compose with
`render`
+
`mergeProps`

2) 结合
`render`
+
`mergeProps`
进行组件组合