Shadcn UI Migration Guide: Transitioning from Radix UI to Base UI

[yluiop123]

Shadcn UI Migration Guide: Transitioning from Radix UI to Base UI

This guide documents the key steps and common pitfalls when migrating the Shadcn UI infrastructure from Radix UI to Base UI.

Core Recommendation: Avoid a "big bang" global replacement. Due to API differences between the two libraries, it is recommended to adopt a gradual, component-by-component replacement strategy.

Reference Project

The migration has been largely completed in a Vite environment. You can compare the differences between the two branches:

• Repository: [vite-shadcn](https://github.com/yluiop123/vite-shadcn)

• Branches: Compare radix-ui (Legacy) vs main (Base UI-driven)

---

1. Recommended Migration Order

To minimize debugging difficulty, migrate components based on their dependency depth:

1. Independent Components: Port atomic components in src/components/ui that do not depend on other components (e.g., Button, Badge).

2. Composite Components: Port other components within src/components/ui that have internal dependencies.

3. Secondary Extensions: Port business components built on top of your local UI components.

4. Native Extensions: Port advanced components that directly extend the original radix-ui APIs.

5. Global Regression Testing: Address remaining style deviations and interaction issues.

---

2. Environment Initialization & Component Updates

There are two ways to introduce Base UI-based components:

Option A: CLI Automation (Recommended)

1. Update components.json: Change "style": "new-york" to "style": "base-vega".

2. Execute the overwrite command:

Bash

pnpm dlx shadcn@latest add --all --overwrite
# Or add specific components
pnpm dlx shadcn@latest add <component-name>

Option B: Manual Migration

1. Install dependencies: pnpm add @base-ui/react.

2. Copy the code from the [Shadcn UI Official Website](https://ui.shadcn.com/) into the corresponding files under src/components/ui.

---

3. Key API Changes & Pitfalls

Remove asChild Attribute

Base UI handles component rendering differently; you must globally remove the asChild keyword from your components.

Checkbox

• Type Constraint: The checked parameter now strictly requires a boolean type.

• Indeterminate State: Use the new indeterminate parameter to support partial selection.

ToggleGroup

• Input Values: The value prop now strictly accepts an array.

• Selection Logic: Use the multiple field to explicitly distinguish between single and multiple selection modes.

Resizable

The official Base UI Resizable component may trigger errors in certain scenarios.

• Fix Reference: A patched implementation is available in the reference project.

Form Components: Transition to Field

It is recommended to deprecate the existing Form system in favor of the Base UI Field component. This involves significant logic changes; please refer to the official documentation or the reference project.

Styles & Positioning: Replacing Radix Selectors

• Search Keywords: Search the project for radix keywords (e.g., data-[state=...].radix-...) within custom component styles.

• Positioning Engine: Base UI relies on Floating UI for popover logic. Custom components requiring positioning should now utilize the @floating-ui/react package.

---

4. Cleanup

Once all components are verified and stable, remove the legacy Radix dependencies:

Bash

pnpm uninstall @radix-ui/react-accordion @radix-ui/react-dialog @radix-ui/react-che