Base UI（@base-ui/react）是一个无样式 React 组件库，用于构建可访问的用户界面，由 Radix、Material UI 与 Floating UI 的作者打造。组件为 headless、可组合且符合 WAI-ARIA，支持 React 17+ 与现代浏览器，单包可 tree-shaking。注意：本指南不适用于 Radix UI、MUI 或 Shadcn/ui，它们 API 不同。
安装：npm i @base-ui/react。设置上建议在应用根节点加 isolation: isolate 以避免 portal 层叠与 z-index 冲突；iOS 26+ Safari 的 dialog backdrop 需 body { position: relative; }。
组件采用单包命名空间复合模式导入，例如 import { Popover } from '@base-ui/react/popover'。组件完全无样式，需自行提供全部 CSS，可用 CSS 类、data-* 状态属性、CSS 自定义属性，兼容 Tailwind、CSS Modules、CSS-in-JS 与纯 CSS。支持用 render prop 替换默认元素或自定义组件；自定义组件需转发 ref 并展开 props。所有交互组件支持受控与非受控模式。事件处理器接收 (value, eventDetails)，可用 cancel()、allowPropagation() 等方法与 reason 原因。
组件目录涵盖：Dialog、AlertDialog、Popover、Tooltip、PreviewCard、Toast、Menu、ContextMenu、NavigationMenu、Menubar；Form、Field、Fieldset、Input、NumberField、Checkbox、CheckboxGroup、Radio、Select、Combobox、Autocomplete、Switch、Slider、Toggle、ToggleGroup、Button；Accordion、Collapsible、Tabs、ScrollArea、Toolbar、Separator、Progress、Meter、Avatar；以及 CSPProvider、DirectionProvider、mergeProps、useRender 等工具。
限制与常见陷阱：交互组件在 RSC 环境需 'use client'；弹层需遵循 Root > Trigger > Portal > Positioner > Popup > Arrow 结构；状态样式用 data 属性而非切换 className；动画建议 CSS transitions，并动画 opacity 以便检测完成；表单提交需在 Field.Root 设置 name；Select/Combobox 的 Field.Label 需 nativeLabel={false}。更多参考资料见官方仓库 references 目录。