base-ui-react

用途

Base UI React 是 MUI 提供的无样式（unstyled）、可访问（accessible）的 React 组件库，定位为 Radix UI 的替代方案。它提供组件的行为与无障碍能力，但不附带视觉样式，样式完全交由使用者控制。

主要能力

提供 27+ 个可访问组件，包括 Dialog、Select、Popover、Tooltip、Accordion、NumberField、Checkbox、Switch、Tabs、Slider 等。
采用 render props 模式（而非 Radix 的 asChild）。
内置 Floating UI 集成，用于浮层定位。
支持完全自定义样式，可与 Tailwind 或任意 CSS 配合使用。
内置 ARIA 无障碍支持。
相比 Radix UI，树摇（tree-shaking）更好、打包体积更小。

使用方式

安装命令：

bun add @base-ui-components/react

基础 Dialog 示例：

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

基础 Select 示例：

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>

与 Tailwind 配合的 Dialog.Popup 示例：

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

关键规则

应当遵循：

弹层（Dialog、Select、Popover）使用 Portal。
浮动元素使用 Positioner。
模态对话框添加 Backdrop。
使用 Tailwind 或任意 CSS 进行样式设置。
使用 render props（而非 Radix 的 asChild）。
测试无障碍（内置 ARIA）。
处理 Portal 边界情况（SSR、hydration）。
查看 beta 文档以了解破坏性变更。
使用 TypeScript 以获得更好的开发体验。
在目标浏览器上测试。

不应做：

不要使用 asChild（改用 render 函数）。
不要省略弹层的 Portal（会导致定位失效）。
不要省略 Positioner（Floating UI 将无法工作）。
不要假设 API 稳定（属于 beta 软件）。
不要跳过无障碍测试。
不要与 React <19 一起使用（要求 React 19+）。
不要省略模态的 Backdrop。
不要硬编码 z-index（使用 Portal）。
不要跳过 SSR 测试（存在 hydration 问题）。
不要假设与 Radix 兼容（API 不同）。

适用场景

模态对话框（Modal Dialog）。
下拉选择（Dropdown Select）。
工具提示（Tooltip）。
需要无障碍组件、从 Radix UI 迁移、偏好 render props API、需要内置定位能力、希望更小打包体积的场景。

限制与注意事项

当前状态为候选发布版 v1.0.0-rc.0，仍处于 pre-GA 阶段，API 可能变化；稳定版 v1.0 GA 预计不久发布。
要求 React 19+。
与 Radix UI 的 API 不同，不保证兼容。
生产可用性方面：Dialog、Popover、Tooltip、Select、Accordion 相对稳定；NumberField 及复杂表单组件需谨慎使用（API 可能变化）。
迁移路径：v1.0 稳定 GA 预计不久发布，破坏性变更将被记录，可能提供 codemod。
若需要稳定性、偏好 asChild 模式或成熟生态，可考虑 Radix UI。

资源

参考文档（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 - Select 下拉
Tooltip.tsx - Tooltip 组件
migration-example.tsx - Radix 到 Base UI 迁移示例

官方文档：

Base UI: https://base-ui.mui.com/
Components: https://base-ui.mui.com/components/
Migration Guide: https://base-ui.mui.com/base-ui/getting-started/migration/