Base UI React

Package: @base-ui/react v1.2.0 Status: Stable (production-ready) React: 19+ Components: 36+

Installation

pnpm add @base-ui/react

Required CSS — add to your app root to create a stacking context for portaled components:

#root {
  isolation: isolate;
}

Architecture

Base UI implements a compound component pattern where each component is a namespace with sub-parts. All imports use sub-path format:

import { Select } from '@base-ui/react/select';
import { Dialog } from '@base-ui/react/dialog';
import { Tooltip } from '@base-ui/react/tooltip';

Three Render Patterns

Every component supports three ways to control its rendered output:

1. Direct Children (Default) — component renders its default HTML element:

<Dialog.Trigger>Open</Dialog.Trigger>

2. Render Element — pass a JSX element to the render prop:

<Dialog.Trigger render={<a href="#">Open</a>} />

3. Render Function — full control via callback receiving (props, state):

<Dialog.Trigger render={(props, state) => <MyButton {...props} active={state.open} />} />

Important: Base UI uses the render prop. Never use asChild — that is a Radix UI concept and does not exist in Base UI.

Floating Components: Portal > Positioner > Popup

Components like Select, Popover, Tooltip, Menu, Combobox all use the same three-layer nesting pattern for positioned overlays:

<Component.Portal>        {/* Renders into document.body */}
  <Component.Positioner>  {/* Handles positioning relative to anchor */}
    <Component.Popup>     {/* The visible floating element */}
      {/* content */}
    </Component.Popup>
  </Component.Positioner>
</Component.Portal>

Never skip Portal or Positioner — the positioning system depends on this structure.

Positioner props: side, align, sideOffset, alignOffset, collisionAvoidance, collisionPadding

CSS variables available on Positioner for sizing:

• --anchor-width, --anchor-height
• --available-width, --available-height
• --transform-origin

Styling with Data Attributes

Base UI exposes component state via data attributes instead of className toggles:

Animations

Use [data-starting-style] and [data-ending-style] for enter/exit transitions:

.popup {
  opacity: 1;
  transform: translateY(0);
  transition: opacity 200ms, transform 200ms;
}

.popup[data-starting-style],
.popup[data-ending-style] {
  opacity: 0;
  transform: translateY(-8px);
}

Component Categories

Components are organized into four categories. For detailed API, props, and examples, see the corresponding reference file.

Floating Components

→ See references/floating-components.md

Select, Popover, Tooltip, Menu, Menubar, ContextMenu, Combobox, PreviewCard

Overlay Components

→ See references/overlay-components.md

Dialog, AlertDialog, Drawer

Form Components

→ See references/form-components.md

Field, Fieldset, Form, Input, Checkbox, Radio, NumberField, Slider, Switch, Toggle

Display Components

→ See references/display-components.md

Accordion, Avatar, Button, Tabs, Toast, Toolbar, Progress, ScrollArea, Separator, ToggleGroup, Collapsible

Utilities

→ See references/utilities.md

mergeProps, useRender, CSPProvider, DirectionProvider

Critical Rules

Always

• Use Portal > Positioner > Popup for floating components
• Add isolation: isolate to root CSS
• Use align prop (not alignment)
• Use Select.Item + Select.ItemText (not Option)
• Use [data-active] for Tabs (not [data-selected])
• Use mergeProps when combining multiple prop objects
• Import from sub-paths: '@base-ui/react/component-name'
• Place delay/closeDelay on Tooltip.Trigger, not Tooltip.Root
• Wrap app in Tooltip.Provider for shared tooltip defaults

Never

• Use asChild — Base UI uses render prop instead
• Skip Portal or Positioner for floating components
• Use Radix UI naming conventions (they differ)
• Assume Accordion allows multiple panels by default (multiple defaults to false)
• Place tooltip timing props on Root instead of Trigger