Base UI (React)

Base UI provides unstyled, composable React components. This skill focuses on assembling multi-part components, composing with the render prop, and meeting accessibility requirements while you supply styling.

Quick navigation (references)

Utilities

• references/csp-provider.md
• references/direction-provider.md
• references/merge-props.md
• references/use-render.md

Forms & inputs

• references/form.md
• references/fieldset.md
• references/input.md
• references/number-field.md
• references/otp-field.md
• references/radio.md
• references/select.md
• references/slider.md
• references/switch.md

Feedback & status

• references/meter.md
• references/progress.md
• references/toast.md

Menus, navigation, overlays

• references/drawer.md
• references/menu.md
• references/menubar.md
• references/navigation-menu.md
• references/popover.md
• references/preview-card.md
• references/tabs.md
• references/tooltip.md

Toggles & controls

• references/toggle.md
• references/toggle-group.md
• references/toolbar.md

Layout & separators

• references/scroll-area.md
• references/separator.md

Release Highlights (1.9.0)

• Menu filtering (preview): <Menu.FilterProvider> wraps a <Menu.Root> or <Menu.SubmenuRoot>, <Menu.Input> takes the query, and <Menu.List> holds the items that get filtered. <Menu.Clear> and <Menu.Empty> cover reset and no-match states. Full details in references/menu.md.
• Unmount control: automatic unmounting is decoupled from actionsRef. Call eventDetails.preventUnmountOnClose() inside onOpenChange to keep the popup mounted, then end the closing phase yourself with actionsRef.current.unmount(). Applies to Autocomplete, Combobox, Menu, Select, Dialog, Alert Dialog, Popover, Tooltip, and Preview Card. Details in references/popover.md.
• Menu.Root accepts onItemHighlighted(highlightedItem, eventDetails). The reason is 'keyboard', 'pointer', or 'none'; pointer events may be a MouseEvent rather than a PointerEvent, and typing reports 'none'.
• Autocomplete and Combobox support autoHighlight with asynchronous results, accept readonly arrays for multiple values, and report the originating event to onItemHighlighted.
• Menu fixes nested menus without a root trigger, submenu closing when focus returns through its guard, repeated trigger activation toggling submenus, and the focus-guard loop when the trigger is the only tabbable element.
• Drawer preserves swipe release velocity on 120 Hz input and after a trailing stationary pointer event, data-base-ui-swipe-ignore gains x and y options, and a drag starting on an SVG scrolls instead of swiping.
• Accordion.Trigger and Collapsible.Trigger apply the native disabled attribute when rendering native buttons, and hiddenUntilFound panels expand synchronously on beforematch.
• Radio Group and Checkbox prefer aria-label over an associated label, ignored arrow keys no longer select on refocus, and inputRef forwarding is fixed.
• NumberField.ScrubArea fires onClick once per click, and OTPField no longer over-fills slots during Safari IME composition.
• Field.Control no longer warns when an uncontrolled defaultValue changes, ScrollArea drops the presentational viewport role, and Tabs can select tabs with function values.
• The CssVariables and DataAttributes types are now exported.

v1.7.0 - v1.8.0 highlights

• Combobox adds a createItems collection API for building the option collection programmatically.
• Avatar.Image adds a keepMounted prop so the image subtree stays mounted (useful for avoiding remount flashes).
• Toast accepts functional updates derived from the current toast, and the render prop is honored in Toast.Title, Toast.Description, and Toast.Action.
• Autocomplete and Combobox emit input-press and cancel-open change event details; inline Combobox exposes an expanded state.
• Combobox.Item and Select.Item inherit the disabled state from their root.
• Form focuses the first invalid field in document order; Field publishes neutral validity while async validation is in flight.
• Mostly accessibility fixes, popup/overlay behavior fixes, and bundle-size reductions across drawers, menus, tooltips, and scroll areas.

v1.4.1 highlights

• mergeProps now forwards multi-argument event handlers correctly, which matters for wrapped callbacks that receive extra details/state alongside the event.
• Tabbability with display: contents was fixed; retest custom wrappers and render-prop compositions that flatten DOM structure.
• Popup sizing on rapid trigger hover was fixed, and clipped-item highlight clearing inside scroll containers is more reliable.

v1.6.0 highlights

• OTPFieldPreview namespace is renamed to OTPField; update imports that referenced the preview namespace.
• Broad behavioral bug fixes across Accordion, Alert Dialog, Autocomplete, Avatar, Checkbox, Dialog, Drawer, Field, Menu, Number Field, OTP Field, and other components.

v1.5.0 highlights

• OTPField replaces sanitizeValue() with normalizeValue() and improves keyboard shortcut plus validation-composition behavior.
• Popup-based components now respect controlled open state more consistently, which affects Popover, Menu, PreviewCard, and related overlays.
• Form, Field, and OTPField avoid older flushSync-style validation timing patterns; retest any local validation scheduling workarounds before keeping them.
• RTL behavior is corrected across NavigationMenu, Popover, and ScrollArea.
• Drawer.Viewport now forwards style, which is useful for custom viewport sizing and animated layout constraints.

v1.4.0 highlights

• OTPField arrives as a preview primitive for one-time-password and verification-code entry.
• Hidden inputs expose form and suppressHydrationWarning, which matters when controls submit to external forms or hydrate across SSR boundaries.
• render warnings and preventBaseUIHandler() runtime behavior are more reliable in composed components.
• Overlay/input primitives received important behavioral fixes across Drawer, NavigationMenu, Select, Slider, Toast, and Switch.

v1.3.0 highlights

• Drawer is now stable (no longer preview) and should be treated as a first-class overlay primitive.
• Autocomplete and Combobox add InputGroup; Combobox, Select, and Slider add Label parts.
• Drawer adds SwipeArea for explicit swipe affordances.
• Tooltip adds closeOnClick; Toast can close all toasts.
• Checkbox, Radio Group, and Switch improve automatic aria-labelledby support.
• render prop support from v1.2.0 remains relevant, including lazy elements.

Core concepts to apply

• Unstyled primitives: all visuals come from your CSS/Tailwind/CSS Modules. Base UI handles behavior and accessibility.
• Multi-part anatomy: most components follow Root + subparts (Trigger, Popup, Item, etc.). Assemble them explicitly.
• render prop: replace the default element or wrap with your own component; when using the function form, merge props manually with mergeProps.
• State-driven styling: many parts expose data attributes such as data-[popup-open], data-[highlighted], data-[pressed], data-[checked], data-[invalid], etc.
• Portals for overlays: use Portal + Positioner + Popup for popovers, menus, tooltips, select, navigation menu content, and preview cards.

Recipes

1) Build accessible forms quickly

• Wrap inputs with Form for submission and error aggregation.
• Use Field.Root with a name, then Field.Label, Field.Control, and Field.Error for labels and errors.
• Group related fields with Fieldset.Root + Fieldset.Legend.
• For Radio groups, either use RadioGroup with aria-labelledby, or render RadioGroup via Fieldset.Root and use Field.Label for each option.
• Ensure every form control has an accessible name (label or Field/Fieldset labeling pattern).

2) Compose with render + mergeProps

• When passing a React element to render, Base UI merges props automatically.
• When passing a function to render, merge Base UI props and your props with mergeProps.
• Use event.preventBaseUIHandler() inside merged event handlers to stop Base UI’s internal behavior when needed (synthetic events only).

3) Overlays and menus (portaled UI)

• Build popups using Root + Trigger + Portal + Positioner + Popup.
• For menus and navigation, add Item, Separator, Arrow, and list/viewport parts as needed.
• NavigationMenu.Link supports render for framework router links.
• To drive the close animation from an external library, call eventDetails.preventUnmountOnClose() in onOpenChange and finish with actionsRef.current.unmount(); keepMounted on the portal decides whether the DOM node stays.

4) Toasts

• Wrap the app (or a subtree) with Toast.Provider.
• Use Toast.useToastManager() to create toasts.
• Render a Toast.Viewport inside Toast.Portal, then map toasts to Toast.Root entries with Toast.Content, Toast.Title, Toast.Description, and Toast.Close.

5) RTL and CSP constraints

• For RTL behavior, wrap with DirectionProvider and also set dir="rtl" (provider does not set the DOM direction).
• For strict CSP, wrap with CSPProvider and pass nonce, or disable inline style elements if your app supplies external styles. Beware inline style attributes are not controlled by CSPProvider.

6) Sliders and ranges

• Single value sliders: one Slider.Thumb.
• Range sliders: pass an array and render a Slider.Thumb per value; add index for SSR alignment.
• Adjust thumb alignment with thumbAlignment when edge alignment is required.

Critical prohibitions

• Do not omit accessible labels for inputs, sliders, switches, or radio groups.
• Do not expect Base UI to provide default styling; apply your own styles.
• Do not forget Portal for overlays that need to escape stacking/overflow contexts.
• Do not skip mergeProps when using the function form of render.

Output expectations

When responding to the user, provide:

• The specific Base UI components to use (and their key parts).
• A brief assembly plan (Root + parts + portal/positioner where relevant).
• A short checklist for accessibility and state-driven styling.

Links

• Documentation
• Releases
• GitHub
• npm