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

```bash
bun add @base-ui-components/react
```

### Basic Dialog

```typescript
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

```typescript
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 ✅

1. **Use Portal** for popups (Dialog, Select, Popover)
2. **Use Positioner** for floating elements
3. **Add Backdrop** for modal dialogs
4. **Style with Tailwind** (or any CSS)
5. **Use render props** (not asChild like Radix)
6. **Test accessibility** (ARIA built-in)
7. **Handle Portal edge cases** (SSR, hydration)
8. **Check beta docs** for breaking c