Skip to content

secondsky/claude-skills / plugins/base-ui-react/skills/base-ui-react

base-ui-react

Verified

MUI Base UI unstyled React components with Floating UI. Use for accessible components, Radix UI migration, render props API, or encountering positioning, popup, v1.0 rc / pre-GA issues.

references/migration-from-radix.md

View on GitHub
# Migration Guide: Radix UI → Base UI

Complete guide to migrating from Radix UI to Base UI.

---

## Quick Reference

| Pattern | Radix UI | Base UI |
|---------|----------|---------|
| Prop merging | `asChild` | `render={(props) => ...}` |
| Positioning | `side`, `align` | `<Positioner side alignment>` |
| Content component | `Content` | `Popup` |
| Overlay component | `Overlay` | `Backdrop` |
| Alignment prop | `align` | `alignment` |
| Portal | Automatic | Explicit `<Portal>` |

---

## Step-by-Step Migration

### Step 1: Update Dependencies

```bash
# Remove Radix
pnpm remove @radix-ui/react-dialog @radix-ui/react-popover @radix-ui/react-select

# Add Base UI
pnpm add @base-ui-components/react
```

### Step 2: Update Imports

```tsx
// Before (Radix)
import * as Dialog from "@radix-ui/react-dialog";
import * as Popover from "@radix-ui/react-popover";
import * as Select from "@radix-ui/react-select";

// After (Base UI)
import { Dialog } from "@base-ui-components/react/dialog";
import { Popover } from "@base-ui-components/react/popover";
import { Select } from "@base-ui-components/react/select";
```

### Step 3: Replace asChild with Render Props

```tsx
// Before (Radix)
<Dialog.Trigger asChild>
  <button className="btn">Open</button>
</Dialog.Trigger>

// After (Base UI)
<Dialog.Trigger
  render={(props) => (
    <button {...props} className="btn">
      Open
    </button>
  )}
/>
```

### Step 4: Add Positioner for Popups

```tsx
// Before (Radix Select)
<Select.Portal>
  <Select.Content side="bottom" align="start">
    <Select.Viewport>
      {/* options */}
    </Select.Viewport>
  </Select.Content>
</Select.Portal>

// After (Base UI Select)
<Select.Positioner side="bottom" alignment="start">
  <Select.Portal>
    <Select.Popup render={(props) => <div {...props}>{/* options */}</div>} />
  </Select.Portal>
</Select.Positioner>
```

### Step 5: Rename Components

- `Content` → `Popup`
- `Overlay` → `Backdrop`
- `align` → `alignment`
- `Viewport` → Remove (not needed)

---

## Component-by-Component Guide

### Dialog

**Radix**:
```tsx
<Dialog.Root>
  <Dialog.Trigger asChild>
    <button>Open</button>
  </Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay className="overlay" />
    <Dialog.Content className="content">
      <Dialog.Title>Title</Dialog.Title>
      <Dialog.Description>Description</Dialog.Description>
      <Dialog.Close asChild>
        <button>Close</button>
      </Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>
```

**Base UI**:
```tsx
<Dialog.Root>
  <Dialog.Trigger render={(props) => <button {...props}>Open</button>} />
  <Dialog.Portal>
    <Dialog.Backdrop render={(props) => <div {...props} className="overlay" />} />
    <Dialog.Popup render={(props) => (
      <div {...props} className="content">
        <Dialog.Title render={(p) => <h2 {...p}>Title</h2>} />
        <Dialog.Description render={(p) => <p {...p}>Description</p>} />
        <Dialog.Close render={(p) => <button {...p}>Close</button>} />
      </div>
    )} />
  </Dialog.Portal>
</Dialog.Root>
```

### Popover

**Radix**:
```tsx
<Popover.Root>
  <Popover.Trigger asChild>
    <button>Open</button>
  </Popover.Trigger>
  <Popover.Portal>
    <Popover.Content side="top" align="center">
      <Popover.Arrow />
      Content
      <Popover.Close asChild>
        <button>Close</button>
      </Popover.Close>
    </Popover.Content>
  </Popover.Portal>
</Popover.Root>
```

**Base UI**:
```tsx
<Popover.Root>
  <Popover.Trigger render={(props) => <button {...props}>Open</button>} />
  <Popover.Positioner side="top" alignment="center">
    <Popover.Portal>
      <Popover.Popup render={(props) => (
        <div {...props}>
          Content
          <Popover.Close render={(p) => <button {...p}>Close</button>} />
        </div>
      )} />
      <Popover.Arrow render={(props) => <div {...props} />} />
    </Popover.Portal>
  </Popover.Positioner>
</Popover.Root>
```

### Select

**Radix**:
```tsx
<Select.Root>
  <Select.Trigger asChild>
    <button>
      <Select.Value placeholder="Select..." />
      <Select.Icon>▼</Select.Icon>
    </button>
  </Select.Trigger>
  <Select.Portal>
    <Select.Content>
      <Select.Viewport>
        <Select.Item value="1" asChild>
          <div>Option 1</div>
        </Select.Item>
      </Select.Viewport>
    </Select.Content>
  </Select.Portal>
</Select.Root>
```

**Base UI**:
```tsx
<Select.Root>
  <Select.Trigger render={(props) => (
    <button {...props}>
      <Select.Value render={(p) => <span {...p} placeholder="Select..." />} />
      <Select.Icon render={(p) => <span {...p}>▼</span>} />
    </button>
  )} />
  <Select.Positioner side="bottom" alignment="start">
    <Select.Portal>
      <Select.Popup render={(props) => (
        <div {...props}>
          <Select.Option value="1" render={(p) => <div {...p}>Option 1</div>} />
        </div>
      )} />
    </Select.Portal>
  </Select.Positioner>
</Select.Root>
```

---

## Common Migration Issues

### Issue: Props not applied
```tsx
// ❌ Wrong
<Trigger render={() => <button>Click</button>} />

// ✅ Correct
<Trigger render={(props) => <button {...props}>Click</button>} />
```

### Issue: Popup won't position
```tsx
// ❌ Wrong (missing Positioner)
<Popover.Portal>
  <Popover.Popup />
</Popover.Portal>

// ✅ Correct
<Popover.Positioner side="top">
  <Popover.Portal>
    <Popover.Popup />
  </Popover.Portal>
</Popover.Positioner>
```

### Issue: TypeScript errors
```tsx
// ❌ Wrong (Radix prop names)
<Positioner align="center" />
<Dialog.Content />
<Dialog.Overlay />

// ✅ Correct (Base UI prop names)
<Positioner alignment="center" />
<Dialog.Popup />
<Dialog.Backdrop />
```

---

## Automated Migration Script

Use the bundled script to automatically convert files:

```bash
./scripts/migrate-radix-component.sh src/components/Dialog.tsx
```

This will:
1. Replace `asChild` with `render` props
2. Add `Positioner` where needed
3. Rename `Content` → `Popup`, `Overlay` → `Backdrop`
4. Update `align` → `alignment`
5. Make `Portal` explicit

---

## Testing After Migration

**Checklist**:
- [ ] All components render correctly
- [ ] Keyboard navigation works (Tab, Escape, Arrow keys)
- [ ] Screen reader announces elements properly
- [ ] Popups position correctly near viewport edges
- [ ] Styling is preserved
- [ ] TypeScript compiles without errors
- [ ] No console warnings/errors

**Test with**:
- Keyboard only (no mouse)
- Screen reader (NVDA, JAWS, VoiceOver)
- Different viewport sizes
- Dark mode (if applicable)

---

## Migration Timeline Estimates

| Component Count | Estimated Time |
|----------------|----------------|
| 1-5 components | 1-2 hours |
| 6-10 components | 2-4 hours |
| 11-20 components | 4-8 hours |
| 20+ components | 1-2 days |

**Note**: Time includes testing and fixing edge cases.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall