Base UI React 是针对 Base UI（@base-ui-components/react）的生产验证配置方案。Base UI 是 MUI 推出的无样式、可访问的 React 组件库，使用 render prop API，而不是 Radix 的 asChild 模式。
状态与依赖
当前状态为 Beta（v1.0.0-beta.4），稳定版 v1.0 预计 2025 年 Q4 发布，文档更新日期为 2025-11-07。依赖要求：React 19+，推荐 Vite，推荐 Tailwind v4，最新版本为 @base-ui-components/react@1.0.0-beta.4。
Beta 状态提示：核心组件（Dialog、Popover、Tooltip、Select、Accordion）已可用于生产；v1.0 前可能出现少量破坏性变更；已在真实项目中使用并有文档化的绕过方案；已知问题有 10 余个并附解决方案；提供从 Radix UI 迁移的指南。建议新项目若可接受 Beta 软件可使用，关键生产应用建议等待 v1.0。
快速开始
安装命令：pnpm add @base-ui-components/react。该单一包内含 27+ 可访问组件，除 React 外无 peer 依赖，支持 tree-shaking，可与任意样式方案（Tailwind、CSS Modules、Emotion 等）配合。
首个组件示例使用 Dialog 的 render prop 写法，要点包括：始终展开 render 函数传入的 {...props}；使用 Dialog.Portal 渲染到 DOM 层级之外；Backdrop 与 Popup 是两个独立组件（不同于 Radix 合并的 Overlay + Content）。
Render Prop 模式
Base UI 用 render props 替代 Radix 的 asChild，优势为：显式的 prop 展开、更好的 TypeScript 支持、更易调试、组合灵活。对比：Radix 用 <Dialog.Trigger asChild><button>Open</button></Dialog.Trigger>；Base UI 用 <Dialog.Trigger render={(props) => (<button {...props}>Open</button>)} />。关键差异是 render prop 让 prop 展开显式化。
Positioner 模式（集成 Floating UI）
Select、Popover、Tooltip 等浮动组件需用 Positioner 包裹：Positioner 负责 Floating UI 定位，Popup 需置于 Portal 内。定位选项包括 side（top/right/bottom/left）、alignment（start/center/end）、sideOffset、alignmentOffset、collisionBoundary、collisionPadding。
组件清单
需要 Positioner 的组件：Select、Popover、Tooltip。不需要 Positioner 的组件：Dialog、Accordion、NumberField、Checkbox、Radio、Switch、Slider。
已知问题预防
该技能可预防 10+ 个已记录问题，包括：render prop 未展开 props；缺少 Positioner 包裹导致定位错误；使用 Radix 的 align 而非 Base UI 的 alignment；使用 asChild 模式；期望自动 Portal（Base UI 需显式 Portal）；Arrow 组件未设置样式导致不可见；沿用 Radix 命名（Content 应为 Popup、Overlay 应为 Backdrop）；禁用按钮的 Tooltip 不显示（需包裹 span）；Select 使用空字符串值影响无障碍。
关键规则
始终：在 render 函数中展开 props；对 Select、Popover、Tooltip 使用 Positioner；对 Dialog、Popover 使用 Portal；使用 alignment 而非 align；显式为 Arrow 设置样式；测试键盘导航与屏幕阅读器。绝不：使用 asChild；忘记展开 props；跳过 Positioner；期望自动 Portal；使用 Radix 命名；使用空字符串作为值；假设 API 稳定。
配置与常见模式
Vite 配置无需特殊设置，兼容标准 React 插件。tsconfig 使用标准 Vite + React TypeScript 配置，render prop 模式有完整类型支持。常见模式包括：带表单提交的 Dialog（含 open/onOpenChange 状态管理）；可搜索的 Select（含搜索过滤、Positioner、Portal 与 Option）。文档中还提供 Arrow 样式、Select 空值等更多代码示例。