base-ui-react

Base UI React

状态：候选发布版（v1.0.0-rc.0）⚠️ | 上次验证时间：2026-08-03

---

什么是 Base UI？

MUI 的无样式、无障碍 React 组件库：

• 27+ 个无障碍组件
• Render props 模式
• 完全的样式控制
• 集成 Floating UI
• Radix UI 的替代方案

候选发布版状态： v1.0.0-rc.0（预计很快发布稳定版 v1.0 GA——目前仍处于 GA 前阶段，API 可能会变化）

---

快速开始

安装

bun add @base-ui-components/react

基本对话框

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>
  );
}

基本选择框

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 查看完整示例。

---

核心组件

可用组件（27+ 个）：

• Dialog
• Select
• Popover
• Tooltip
• Accordion
• NumberField
• Checkbox
• Switch
• Tabs
• Slider
• 以及更多……

---

关键规则

始终执行 ✅

1. 为弹出内容使用 Portal（Dialog、Select、Popover）
2. 为浮动元素使用 Positioner
3. 为模态对话框添加 Backdrop
4. 使用 Tailwind 设置样式（或使用任意 CSS）
5. 使用 render props（不要像 Radix 那样使用 asChild）
6. 测试无障碍功能（内置 ARIA）
7. 处理 Portal 边缘情况（SSR、水合）
8. 查看 beta 文档，了解破坏性变更
9. 使用 TypeScript，改善开发体验
10. 在目标浏览器上测试

绝不执行 ❌

1. 绝不使用 asChild（改用 render 函数）
2. 绝不跳过弹出内容的 Portal（会导致定位失效）
3. 绝不跳过 Positioner（Floating UI 将无法工作）
4. 绝不假设 API 稳定（这是 beta 软件）
5. 绝不跳过无障碍测试
6. 绝不与 React <19 一起使用（需要 React 19+）
7. 绝不为模态框跳过 Backdrop
8. 绝不硬编码 z-index（使用 Portal）
9. 绝不跳过 SSR 测试（可能出现水合问题）
10. 绝不假设与 Radix 兼容（API 不同）

---

搭配 Tailwind 使用

<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>

---

常见用例

用例 1：模态对话框

<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>

用例 2：下拉选择框

<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>

用例 3：工具提示

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 版本注意事项

可稳定用于生产环境：

• Dialog
• Popover
• Tooltip
• Select
• Accordion

谨慎使用：

• NumberField（API 可能会变化）
• 复杂表单组件

迁移路径：

• 预计很快发布 v1.0 稳定 GA（目前为 v1.0.0-rc.0）
• 将记录破坏性变更
• 可能会提供 Codemods

---

与 Radix UI 对比

特性	Base UI	Radix UI
模式	Render props	asChild
定位	内置 Floating UI	手动
Beta	是	稳定版
Tree-shaking	更好	良好
包体积	更小	更大

适合使用 Base UI 的情况：

• 更喜欢 render props
• 需要内置定位
• 希望减小包体积
• 可以接受 beta 版本

适合使用 Radix 的情况：

• 需要稳定性
• 更喜欢 asChild 模式
• 需要成熟的生态系统

---

资源

参考资料（references/）：

• example-reference.md - 详细的组件示例和模式
• migration-from-radix.md - 从 Radix UI 迁移的完整指南（包括 render prop 模式说明）
• setup-guide.md - 安装和设置指南

模板（templates/）：

• Accordion.tsx - 使用 render props 的 Accordion 组件
• Dialog.tsx - 模态对话框示例
• NumberField.tsx - 带验证的数字输入框
• Popover.tsx - 带定位功能的 Popover
• Select.tsx - 下拉选择框
• Tooltip.tsx - Tooltip 组件
• migration-example.tsx - 从 Radix 迁移到 Base UI 的示例

---

官方文档

• Base UI：https://base-ui.mui.com/
• 组件：https://base-ui.mui.com/components/
• 迁移指南：https://base-ui.mui.com/base-ui/getting-started/migration/

---

有疑问？遇到问题？

1. 查看 references/setup-guide.md 了解设置方法
2. 留意 beta 状态警告
3. 查阅官方文档获取最新更新
4. 如果需要稳定性，可考虑使用 Radix