Base UI Guide
Base UI (@base-ui/react ) is an unstyled React component library for building accessible user interfaces. From the creators of Radix, Material UI, and Floating UI. Components are headless, composable, and WAI-ARIA compliant. Supports React 17+ and all modern browsers (Baseline Widely Available). Tree-shakable single package.
Do NOT use this guide for Radix UI (radix-ui), Material UI (MUI @mui/material), or Shadcn/ui — those are separate libraries with different APIs.
Quick Start
npm i @base-ui/react
Setup
- Portals - Add stacking context isolation to prevent z-index conflicts:
.root { isolation: isolate; }
<body><div className="root">{children}</div></body>
- iOS 26+ Safari - For dialog backdrops:
body { position: relative; }
Import Pattern
All components use namespaced compound pattern from a single package:
import { Popover } from '@base-ui/react/popover';
<Popover.Root> <Popover.Trigger>Open</Popover.Trigger> <Popover.Portal> <Popover.Positioner sideOffset={8}> <Popover.Popup> <Popover.Arrow /> <Popover.Title>Title</Popover.Title> <Popover.Description>Content</Popover.Description> </Popover.Popup> </Popover.Positioner> </Popover.Portal> </Popover.Root>
Core Patterns
Styling (components are completely unstyled)
CSS Classes - static or state-dependent:
<Switch.Thumb className="SwitchThumb" /> <Switch.Thumb className={(state) => state.checked ? 'checked' : 'unchecked'} />
Data Attributes - all components expose state via data-* attributes:
.SwitchThumb[data-checked] { background: blue; } .Popup[data-starting-style] { opacity: 0; transform: scale(0.9); }
CSS Custom Properties - dynamic values for layout/animation:
.Indicator { width: var(--slider-indicator-width); } .Popup { transform-origin: var(--transform-origin); }
Works with Tailwind CSS, CSS Modules, CSS-in-JS, or plain CSS.
Composition (render prop)
Replace default elements with custom components or different HTML tags:
// Custom component (must forward ref and spread props) <Dialog.Trigger render={<MyButton size="md" />} />
// Different HTML element <Menu.Item render={<a href="/profile" />}>Profile</Menu.Item>
// Render function with state access <Checkbox.Root render={(props, state) => ( <span {...props}>{state.checked ? <CheckIcon /> : <BoxIcon />}</span> )} />
Server Components (Next.js / RSC)
All interactive Base UI components require 'use client' in React Server Component environments. Only static display components (Separator, Avatar without interaction) can be used in server components.
Combobox List Render Pattern
Combobox and Autocomplete use a unique render-children pattern on List — pass a function that receives each filtered item:
<Combobox.List> {(item) => ( <Combobox.Item key={item.value} value={item}> {item.label} </Combobox.Item> )} </Combobox.List>
This differs from Select, where you explicitly .map() over items inside Select.List .
Controlled vs Uncontrolled
All interactive components support both modes:
// Uncontrolled (internal state) <Dialog.Root defaultOpen={false}>
// Controlled (external state) <Dialog.Root open={isOpen} onOpenChange={setIsOpen}>
Event Customization
Change handlers receive (value, eventDetails) :
<Dialog.Root onOpenChange={(open, details) => { if (details.reason === 'escape-key') { details.cancel(); // Prevent closing } }}>
Key eventDetails methods: cancel() , allowPropagation() . Access reason for why the change occurred.
Animation
CSS Transitions (recommended - can be cancelled midway):
.Popup { transition: transform 150ms, opacity 150ms; transform-origin: var(--transform-origin); } .Popup[data-starting-style], .Popup[data-ending-style] { opacity: 0; transform: scale(0.9); }
CSS Animations: Use [data-open] / [data-closed] with @keyframes .
JavaScript (Motion): Use keepMounted
- render prop + <AnimatePresence> .
TypeScript
Types organized by namespace:
Tooltip.Root.Props // Component props Popover.Positioner.State // Internal state type Combobox.Root.ChangeEventDetails // Event details type
Component Catalog
Overlay & Navigation
Component Parts Description
Dialog Root, Trigger, Portal, Backdrop, Popup, Title, Description, Close Modal dialog with focus trap
AlertDialog Root, Trigger, Portal, Backdrop, Popup, Title, Description, Close Confirmation dialog (no pointer dismiss)
Popover Root, Trigger, Portal, Positioner, Popup, Arrow, Title, Description Non-modal floating content
Tooltip Provider, Root, Trigger, Portal, Positioner, Popup, Arrow Hover/focus info popup
PreviewCard Root, Trigger, Portal, Positioner, Popup, Arrow Link hover preview
Toast Provider, Portal, Viewport, Root, Title, Description, Action, Close Notification toasts (stacked or anchored)
Menu Root, Trigger, Portal, Positioner, Popup, Arrow, Item, Group, Separator + Radio/Checkbox items Dropdown menu with submenus
ContextMenu Root, Trigger, Portal, Positioner, Popup, Item, Group + submenus Right-click context menu
NavigationMenu Root, List, Item, Trigger, Content, Portal, Positioner, Popup, Link Site navigation with panels
Menubar Wrapper + Menu.Root instances Horizontal application menu bar
Form Controls
Component Parts Description
Form Single wrapper Form with validation and submission
Field Root, Label, Control, Description, Error, Validity Field wrapper with validation
Fieldset Root, Legend Groups related fields
Input Single element Text input with state data attributes
NumberField Root, ScrubArea, Group, Decrement, Input, Increment Numeric input with stepper
Checkbox Root, Indicator Checkbox with indeterminate support
CheckboxGroup Root Manages multiple checkbox state
Radio Root, Indicator + RadioGroup Radio button group
Select Root, Trigger, Value, Portal, Positioner, Popup, List, Item, ItemIndicator Dropdown select
Combobox Root, Input, Trigger, Portal, Positioner, Popup, List, Item + chips Searchable select with filtering
Autocomplete Root, Input, Trigger, Portal, Positioner, Popup, List, Item Text input with suggestions
Switch Root, Thumb Toggle switch
Slider Root, Value, Control, Track, Indicator, Thumb Range slider (single or multi-thumb)
Toggle Single element Pressable toggle button
ToggleGroup Wrapper + Toggle children Exclusive or multi-select toggles
Button Single element Accessible button
Display & Layout
Component Parts Description
Accordion Root, Item, Header, Trigger, Panel Expandable content sections
Collapsible Root, Trigger, Panel Single expand/collapse
Tabs Root, List, Tab, Indicator, Panel Tabbed interface
ScrollArea Root, Viewport, Content, Scrollbar, Thumb, Corner Custom scrollbars
Toolbar Root, Button, Link, Separator, Group, Input Action toolbar
Separator Single element Visual divider
Progress Root, Track, Indicator, Value, Label Progress bar
Meter Root, Track, Indicator, Value, Label Gauge/meter display
Avatar Root, Image, Fallback Profile image with fallback
Utilities
Utility Purpose
CSPProvider Apply nonce to inline styles/scripts for CSP
DirectionProvider Enable RTL behavior for components
mergeProps Merge React props with special handler/class/style merging
useRender Hook to enable render prop pattern in custom components
Key Rules
-
Always use isolation: isolate on app root for portal z-index stacking
-
Components are unstyled - you must provide all CSS
-
Custom components in render must forward ref and spread props
-
Use data attributes for state-based styling, not className toggling
-
CSS transitions > CSS animations for interruptible open/close effects
-
Animate opacity (even 0.9999) so Base UI detects animation completion before unmounting
-
Form fields need name prop on Field.Root for form submission
-
Field.Label uses nativeLabel prop - set false for button-based controls (Select, Combobox)
-
Popup components follow: Root > Trigger > Portal > Positioner > Popup > Arrow pattern
-
preventBaseUIHandler() on React events to bypass Base UI's internal event handling
Common Pitfalls
-
Portal z-index issues: Forgot isolation: isolate on app root - popups appear behind content
-
Animation not completing: Not animating opacity
-
Base UI uses element.getAnimations() to detect completion; animate opacity even to 0.9999 if not otherwise needed
-
Select/Combobox label not associating: Need nativeLabel={false} on Field.Label for button-based controls (Select, Combobox)
-
Popup appearing behind content: Missing Portal wrapper or stacking context not set up
-
Form values not collected on submit: Missing name prop on Field.Root
-
Nested popups all close on Esc: Default behavior stops propagation; use eventDetails.allowPropagation() if you want parent popups to also close
-
Motion exit animations not playing: Must use keepMounted on Portal + controlled open state + <AnimatePresence> for unmounted components
Common CSS Variables
Popup/floating components expose:
-
--anchor-width , --anchor-height
-
Trigger element dimensions
-
--available-width , --available-height
-
Available space
-
--transform-origin
-
Animation origin point
Sizing components expose:
-
--accordion-panel-height , --collapsible-panel-height
-
Panel dimensions
-
--slider-* , --scroll-area-*
-
Component-specific sizing
-
--active-tab-left , --active-tab-width
-
Tab indicator positioning
Reference Files
-
references/components-dialogs.md
-
Dialog, AlertDialog, Popover, Tooltip, PreviewCard
-
references/components-menus.md
-
Toast, Menu, ContextMenu, NavigationMenu, Menubar, shared patterns
-
references/components-form-fields.md
-
Form, Field, Fieldset, Input, NumberField, Checkbox, CheckboxGroup, Radio
-
references/components-form-controls.md
-
Select, Combobox, Autocomplete, Switch, Slider, Toggle, ToggleGroup, Button
-
references/components-panels.md
-
Accordion, Collapsible, Tabs, ScrollArea
-
references/components-indicators.md
-
Toolbar, Separator, Progress, Meter, Avatar
-
references/styling.md
-
Complete styling guide (Tailwind, CSS Modules, CSS-in-JS)
-
references/animation.md
-
Animation patterns (CSS transitions, CSS animations, Motion/JS)
-
references/composition.md
-
Composition, customization, and event handling
-
references/forms-typescript.md
-
Form integration and TypeScript type patterns
-
references/utilities.md
-
CSPProvider, DirectionProvider, mergeProps, useRender
-
references/accessibility.md
-
Accessibility features, keyboard navigation, focus management, ARIA