Base UI React

Base UI React

Status: Beta (v1.0.0-beta.4) ⚠️ | Last Verified: 2025-11-18

What Is Base UI?

MUI's unstyled, accessible React component library:

• 27+ accessible components
• Render props pattern
• Full styling control
• Floating UI integration
• Alternative to Radix UI

Beta status: v1.0.0-beta.4 (stable v1.0 expected Q4 2025)

Quick Start

Install

bun add @base-ui-components/react

Basic Dialog

import * as Dialog from '@base-ui-components/react/dialog';

export function MyDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger>Open</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Backdrop />
        <Dialog.Popup>
          <Dialog.Title>Title</Dialog.Title>
          <Dialog.Description>Content</Dialog.Description>
          <Dialog.Close>Close</Dialog.Close>
        </Dialog.Popup>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

Basic Select

import * as Select from '@base-ui-components/react/select';

<Select.Root>
  <Select.Trigger>
    <Select.Value placeholder="Select" />
  </Select.Trigger>
  <Select.Portal>
    <Select.Positioner>
      <Select.Popup>
        <Select.Option value="1">Option 1</Select.Option>
        <Select.Option value="2">Option 2</Select.Option>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>

Load references/setup-guide.md for complete examples.

Core Components

Available (27+):

• Dialog
• Select
• Popover
• Tooltip
• Accordion
• NumberField
• Checkbox
• Switch
• Tabs
• Slider
• And more...

Critical Rules

Always Do ✅

• Use Portal for popups (Dialog, Select, Popover)
• Use Positioner for floating elements
• Add Backdrop for modal dialogs
• Style with Tailwind (or any CSS)
• Use render props (not asChild like Radix)
• Test accessibility (ARIA built-in)
• Handle Portal edge cases (SSR, hydration)
• Check beta docs for breaking changes
• Use TypeScript for better DX

10. Test on target browsers

Never Do ❌

• Never use asChild (use render function instead)
• Never skip Portal for popups (positioning breaks)
• Never skip Positioner (Floating UI won't work)
• Never assume API stability (beta software)
• Never skip accessibility testing
• Never use with React <19 (requires React 19+)
• Never skip Backdrop for modals
• Never hardcode z-index (use Portal)
• Never skip SSR testing (hydration issues)

10. Never assume Radix compatibility (different API)

With Tailwind

<Dialog.Popup className="rounded-lg bg-white p-6 shadow-xl dark:bg-gray-800">
  <Dialog.Title className="text-xl font-bold text-gray-900 dark:text-white">
    Dialog Title
  </Dialog.Title>
  <Dialog.Description className="mt-2 text-gray-600 dark:text-gray-300">
    Dialog content here
  </Dialog.Description>
  <Dialog.Close className="mt-4 rounded bg-blue-500 px-4 py-2 text-white hover:bg-blue-600">
    Close
  </Dialog.Close>
</Dialog.Popup>

Common Use Cases

Use Case 1: Modal Dialog

<Dialog.Root>
  <Dialog.Trigger className="btn">Open Modal</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Backdrop className="fixed inset-0 bg-black/50" />
    <Dialog.Popup className="fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 rounded-lg bg-white p-6">
      <Dialog.Title>Confirm Action</Dialog.Title>
      <Dialog.Description>Are you sure?</Dialog.Description>
      <Dialog.Close>Cancel</Dialog.Close>
    </Dialog.Popup>
  </Dialog.Portal>
</Dialog.Root>

Use Case 2: Dropdown Select

<Select.Root>
  <Select.Trigger className="flex items-center gap-2 rounded border px-4 py-2">
    <Select.Value placeholder="Select option" />
  </Select.Trigger>
  <Select.Portal>
    <Select.Positioner className="z-50">
      <Select.Popup className="rounded border bg-white shadow-lg">
        <Select.Option value="1" className="px-4 py-2 hover:bg-gray-100">
          Option 1
        </Select.Option>
        <Select.Option value="2" className="px-4 py-2 hover:bg-gray-100">
          Option 2
        </Select.Option>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>

Use Case 3: Tooltip

import * as Tooltip from '@base-ui-components/react/tooltip';

<Tooltip.Root>
  <Tooltip.Trigger>Hover me</Tooltip.Trigger>
  <Tooltip.Portal>
    <Tooltip.Positioner>
      <Tooltip.Popup className="rounded bg-gray-900 px-2 py-1 text-sm text-white">
        Tooltip text
      </Tooltip.Popup>
    </Tooltip.Positioner>
  </Tooltip.Portal>
</Tooltip.Root>

Beta Considerations

Stable for production:

• Dialog
• Popover
• Tooltip
• Select
• Accordion

Use with caution:

• NumberField (API may change)
• Complex form components

Migration path:

• v1.0 stable expected Q4 2025
• Breaking changes will be documented
• Codemods likely provided

vs Radix UI

| Feature | Base UI | Radix UI |

|---------|---------|----------|

| Pattern | Render props | asChild |

| Positioning | Floating UI built-in | Manual |

| Beta | Yes | Stable |

| Tree-shaking | Better | Good |

| Bundle size | Smaller | Larger |

When to use Base UI:

• Prefer render props
• Need built-in positioning
• Want smaller bundle
• Okay with beta

When to use Radix:

• Need stability
• Prefer asChild pattern
• Established ecosystem

Resources

References (references/):

• example-reference.md - Detailed component examples and patterns
• migration-from-radix.md - Complete migration guide from Radix UI (includes render prop pattern explanation)
• setup-guide.md - Installation and setup walkthrough

Templates (templates/):

• Accordion.tsx - Accordion component with render props
• Dialog.tsx - Modal dialog example
• NumberField.tsx - Number input with validation
• Popover.tsx - Popover with positioning
• Select.tsx - Select dropdown
• Tooltip.tsx - Tooltip component
• migration-example.tsx - Radix to Base UI migration example

Official Documentation

• Base UI: <https://base-ui.mui.com/>
• Components: <https://base-ui.mui.com/components/>
• Migration Guide: <https://base-ui.mui.com/base-ui/getting-started/migration/>

Questions? Issues?

• Check references/setup-guide.md for setup
• Review beta status warnings
• See official docs for latest updates
• Consider Radix if need stability