Back to Details

base-ui-react

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Base UI React

Base UI React

Status: Beta (v1.0.0-beta.4) ⚠️ | Last Verified: 2025-11-18
状态：测试版（v1.0.0-beta.4）⚠️ | 最后验证时间：2025-11-18

What Is Base UI?

什么是Base UI？

MUI's unstyled, accessible React component library:
  • 27+ accessible components
  • Render props pattern
  • Full styling control
  • Floating UI integration
  • Alternative to Radix UI
Beta status: v1.0.0-beta.4 (stable v1.0 expected Q4 2025)
MUI推出的无样式、无障碍React组件库：
  • 27+个无障碍组件
  • Render props模式
  • 完全样式控制
  • 集成Floating UI
  • Radix UI的替代方案
测试版状态：v1.0.0-beta.4（预计2025年第四季度发布稳定版v1.0）

Quick Start

快速开始

Install

安装

bash
bun add @base-ui-components/react
bash
bun add @base-ui-components/react

Basic Dialog

基础Dialog组件

typescript
import * as Dialog from '@base-ui-components/react/dialog';

export function MyDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger>Open</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Backdrop />
        <Dialog.Popup>
          <Dialog.Title>Title</Dialog.Title>
          <Dialog.Description>Content</Dialog.Description>
          <Dialog.Close>Close</Dialog.Close>
        </Dialog.Popup>
      </Dialog.Portal>
    </Dialog.Root>
  );
}
typescript
import * as Dialog from '@base-ui-components/react/dialog';

export function MyDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger>Open</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Backdrop />
        <Dialog.Popup>
          <Dialog.Title>Title</Dialog.Title>
          <Dialog.Description>Content</Dialog.Description>
          <Dialog.Close>Close</Dialog.Close>
        </Dialog.Popup>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

Basic Select

基础Select组件

typescript
import * as Select from '@base-ui-components/react/select';

<Select.Root>
  <Select.Trigger>
    <Select.Value placeholder="Select" />
  </Select.Trigger>
  <Select.Portal>
    <Select.Positioner>
      <Select.Popup>
        <Select.Option value="1">Option 1</Select.Option>
        <Select.Option value="2">Option 2</Select.Option>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>
Load 
references/setup-guide.md
for complete examples.
typescript
import * as Select from '@base-ui-components/react/select';

<Select.Root>
  <Select.Trigger>
    <Select.Value placeholder="Select" />
  </Select.Trigger>
  <Select.Portal>
    <Select.Positioner>
      <Select.Popup>
        <Select.Option value="1">Option 1</Select.Option>
        <Select.Option value="2">Option 2</Select.Option>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>
查看 
references/setup-guide.md
获取完整示例。

Core Components

核心组件

Available (27+):
  • Dialog
  • Select
  • Popover
  • Tooltip
  • Accordion
  • NumberField
  • Checkbox
  • Switch
  • Tabs
  • Slider
  • And more...
已支持（27+个）：
  • Dialog
  • Select
  • Popover
  • Tooltip
  • Accordion
  • NumberField
  • Checkbox
  • Switch
  • Tabs
  • Slider
  • 更多...

Critical Rules

重要规则

Always Do ✅

必须遵循 ✅

  1. Use Portal for popups (Dialog, Select, Popover)
  2. Use Positioner for floating elements
  3. Add Backdrop for modal dialogs
  4. Style with Tailwind (or any CSS)
  5. Use render props (not asChild like Radix)
  6. Test accessibility (ARIA built-in)
  7. Handle Portal edge cases (SSR, hydration)
  8. Check beta docs for breaking changes
  9. Use TypeScript for better DX
  10. Test on target browsers
  1. 为弹窗类组件使用Portal（Dialog、Select、Popover）
  2. 为浮动元素使用Positioner
  3. 为模态Dialog添加Backdrop
  4. 使用Tailwind（或任意CSS）进行样式定制
  5. 使用render props（而非Radix的asChild）
  6. 测试无障碍性（内置ARIA支持）
  7. 处理Portal边缘情况（SSR、 hydration）
  8. 查看测试版文档了解破坏性变更
  9. 使用TypeScript提升开发体验
  10. 在目标浏览器上测试

Never Do ❌

禁止操作 ❌

  1. Never use asChild (use render function instead)
  2. Never skip Portal for popups (positioning breaks)
  3. Never skip Positioner (Floating UI won't work)
  4. Never assume API stability (beta software)
  5. Never skip accessibility testing
  6. Never use with React <19 (requires React 19+)
  7. Never skip Backdrop for modals
  8. Never hardcode z-index (use Portal)
  9. Never skip SSR testing (hydration issues)
  10. Never assume Radix compatibility (different API)
  1. 禁止使用asChild（改用渲染函数）
  2. 禁止为弹窗跳过Portal（会导致定位失效）
  3. 禁止跳过Positioner（Floating UI将无法正常工作）
  4. 不要假设API稳定（测试版软件）
  5. 禁止跳过无障碍测试
  6. 禁止与React <19版本搭配使用（要求React 19+）
  7. 禁止为模态框跳过Backdrop
  8. 禁止硬编码z-index（使用Portal）
  9. 禁止跳过SSR测试（会出现hydration问题）
  10. 不要假设与Radix兼容（API不同）

With Tailwind

搭配Tailwind使用

typescript
<Dialog.Popup className="rounded-lg bg-white p-6 shadow-xl dark:bg-gray-800">
  <Dialog.Title className="text-xl font-bold text-gray-900 dark:text-white">
    Dialog Title
  </Dialog.Title>
  <Dialog.Description className="mt-2 text-gray-600 dark:text-gray-300">
    Dialog content here
  </Dialog.Description>
  <Dialog.Close className="mt-4 rounded bg-blue-500 px-4 py-2 text-white hover:bg-blue-600">
    Close
  </Dialog.Close>
</Dialog.Popup>
typescript
<Dialog.Popup className="rounded-lg bg-white p-6 shadow-xl dark:bg-gray-800">
  <Dialog.Title className="text-xl font-bold text-gray-900 dark:text-white">
    Dialog Title
  </Dialog.Title>
  <Dialog.Description className="mt-2 text-gray-600 dark:text-gray-300">
    Dialog content here
  </Dialog.Description>
  <Dialog.Close className="mt-4 rounded bg-blue-500 px-4 py-2 text-white hover:bg-blue-600">
    Close
  </Dialog.Close>
</Dialog.Popup>

Common Use Cases

常见使用场景

Use Case 1: Modal Dialog

场景1：模态Dialog

typescript
<Dialog.Root>
  <Dialog.Trigger className="btn">Open Modal</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Backdrop className="fixed inset-0 bg-black/50" />
    <Dialog.Popup className="fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 rounded-lg bg-white p-6">
      <Dialog.Title>Confirm Action</Dialog.Title>
      <Dialog.Description>Are you sure?</Dialog.Description>
      <Dialog.Close>Cancel</Dialog.Close>
    </Dialog.Popup>
  </Dialog.Portal>
</Dialog.Root>
typescript
<Dialog.Root>
  <Dialog.Trigger className="btn">Open Modal</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Backdrop className="fixed inset-0 bg-black/50" />
    <Dialog.Popup className="fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 rounded-lg bg-white p-6">
      <Dialog.Title>Confirm Action</Dialog.Title>
      <Dialog.Description>Are you sure?</Dialog.Description>
      <Dialog.Close>Cancel</Dialog.Close>
    </Dialog.Popup>
  </Dialog.Portal>
</Dialog.Root>

Use Case 2: Dropdown Select

场景2：下拉选择器Select

typescript
<Select.Root>
  <Select.Trigger className="flex items-center gap-2 rounded border px-4 py-2">
    <Select.Value placeholder="Select option" />
  </Select.Trigger>
  <Select.Portal>
    <Select.Positioner className="z-50">
      <Select.Popup className="rounded border bg-white shadow-lg">
        <Select.Option value="1" className="px-4 py-2 hover:bg-gray-100">
          Option 1
        </Select.Option>
        <Select.Option value="2" className="px-4 py-2 hover:bg-gray-100">
          Option 2
        </Select.Option>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>
typescript
<Select.Root>
  <Select.Trigger className="flex items-center gap-2 rounded border px-4 py-2">
    <Select.Value placeholder="Select option" />
  </Select.Trigger>
  <Select.Portal>
    <Select.Positioner className="z-50">
      <Select.Popup className="rounded border bg-white shadow-lg">
        <Select.Option value="1" className="px-4 py-2 hover:bg-gray-100">
          Option 1
        </Select.Option>
        <Select.Option value="2" className="px-4 py-2 hover:bg-gray-100">
          Option 2
        </Select.Option>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>

Use Case 3: Tooltip

场景3：Tooltip提示框

typescript
import * as Tooltip from '@base-ui-components/react/tooltip';

<Tooltip.Root>
  <Tooltip.Trigger>Hover me</Tooltip.Trigger>
  <Tooltip.Portal>
    <Tooltip.Positioner>
      <Tooltip.Popup className="rounded bg-gray-900 px-2 py-1 text-sm text-white">
        Tooltip text
      </Tooltip.Popup>
    </Tooltip.Positioner>
  </Tooltip.Portal>
</Tooltip.Root>
typescript
import * as Tooltip from '@base-ui-components/react/tooltip';

<Tooltip.Root>
  <Tooltip.Trigger>Hover me</Tooltip.Trigger>
  <Tooltip.Portal>
    <Tooltip.Positioner>
      <Tooltip.Popup className="rounded bg-gray-900 px-2 py-1 text-sm text-white">
        Tooltip text
      </Tooltip.Popup>
    </Tooltip.Positioner>
  </Tooltip.Portal>
</Tooltip.Root>

Beta Considerations

测试版注意事项

Stable for production:
  • Dialog
  • Popover
  • Tooltip
  • Select
  • Accordion
Use with caution:
  • NumberField (API may change)
  • Complex form components
Migration path:
  • v1.0 stable expected Q4 2025
  • Breaking changes will be documented
  • Codemods likely provided
可稳定用于生产环境的组件：
  • Dialog
  • Popover
  • Tooltip
  • Select
  • Accordion
需谨慎使用的组件：
  • NumberField（API可能变更）
  • 复杂表单组件
迁移路径：
  • 预计2025年第四季度发布v1.0稳定版
  • 破坏性变更将有文档说明
  • 可能提供代码转换工具（Codemods）

vs Radix UI

与Radix UI对比

FeatureBase UIRadix UI
PatternRender propsasChild
PositioningFloating UI built-inManual
BetaYesStable
Tree-shakingBetterGood
Bundle sizeSmallerLarger
When to use Base UI:
  • Prefer render props
  • Need built-in positioning
  • Want smaller bundle
  • Okay with beta
When to use Radix:
  • Need stability
  • Prefer asChild pattern
  • Established ecosystem
特性Base UIRadix UI
模式Render propsasChild
定位内置Floating UI手动配置
版本状态测试版稳定版
树摇优化更优良好
包体积更小更大
何时选择Base UI：
  • 偏好render props模式
  • 需要内置定位功能
  • 希望包体积更小
  • 可以接受测试版状态
何时选择Radix UI：
  • 需要版本稳定性
  • 偏好asChild模式
  • 依赖成熟的生态系统

Resources

资源

References (
references/
):
  • example-reference.md
    - Detailed component examples and patterns
  • migration-from-radix.md
    - Complete migration guide from Radix UI (includes render prop pattern explanation)
  • setup-guide.md
    - Installation and setup walkthrough
Templates (
templates/
):
  • Accordion.tsx
    - Accordion component with render props
  • Dialog.tsx
    - Modal dialog example
  • NumberField.tsx
    - Number input with validation
  • Popover.tsx
    - Popover with positioning
  • Select.tsx
    - Select dropdown
  • Tooltip.tsx
    - Tooltip component
  • migration-example.tsx
    - Radix to Base UI migration example
参考文档（
references/
目录）：
  • example-reference.md
    - 详细的组件示例与模式说明
  • migration-from-radix.md
    - 完整的Radix UI迁移指南（包含render props模式解释）
  • setup-guide.md
    - 安装与配置分步教程
模板（
templates/
目录）：
  • Accordion.tsx
    - 使用render props的Accordion组件
  • Dialog.tsx
    - 模态Dialog示例
  • NumberField.tsx
    - 带验证的数字输入框
  • Popover.tsx
    - 带定位的Popover组件
  • Select.tsx
    - 下拉选择器
  • Tooltip.tsx
    - Tooltip提示框
  • migration-example.tsx
    - Radix UI迁移到Base UI的示例

Official Documentation

官方文档

Questions? Issues?
  1. Check 
    references/setup-guide.md
    for setup
  2. Review beta status warnings
  3. See official docs for latest updates
  4. Consider Radix if need stability
有疑问？遇到问题？
  1. 查看
    references/setup-guide.md
    了解配置方法
  2. 查看测试版状态警告
  3. 查看官方文档获取最新更新
  4. 若需要稳定性，可考虑使用Radix UI