shadcn migrate-radix-to-base skill: move a React app from Radix UI to Base UI

Makes Claude migrate shadcn and Radix UI components to Base UI one at a time, with a report per component.

Installs: 32.7K; on skills.sh
Stars: 127.1K; on GitHub
Files: 9; besides SKILL.md
Updated: Oct 2026; last repo commit

migrate-radix-to-base is a skill in the shadcn/ui repo. Claude checks your project with the shadcn CLI, then moves wrappers and the code that uses them from Radix UI to @base-ui/react. It works one component at a time by default, and keeps the project building at every step.

It uses the Base UI version of your shadcn style when one exists and replays your customisations on top. It never touches cmdk, vaul, sonner and similar libraries. Each run leaves a .migration report per component. It runs shadcn CLI commands, edits many files and makes git commits.

Good for

Teams on shadcn/ui with Radix that want to switch to Base UI
Maintainers with hand-rolled Radix compositions to convert
Anyone who wants a safe, component-by-component migration with reports

Install migrate-radix-to-base

Claude Code

Copy this prompt.

Install the migrate-radix-to-base skill in Claude Code. Run this command:

npx skills add https://github.com/shadcn/ui --skill migrate-radix-to-base

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Migrates React projects and components from Radix UI to Base UI. Use when asked to migrate from radix, move to base-ui, convert radix primitives, or switch a shadcn project's base library. Handles single components ("migrate accordion") and whole projects.

Sections in SKILL.md

Preflight (always)
Strategy: golden pair first, transformation engine second
Modes
Hard rules
Verify and report
Changed
Left alone
Behavior changes
Verify by hand

Key facts

Author: shadcn
Repo: shadcn/ui (now shadcn-ui/ui)
Installs on skills.sh: 32,734 as of Nov 2, 2026
GitHub stars: 127,115 for the whole shadcn/ui repo, Nov 2, 2026
License: MIT
Last repo commit: Oct 31, 2026
What is inside: 10 files including SKILL.md: 9 guides on class mapping, props, menus, overlays, forms and wrapper shapes
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk warn
Skill name: migrate-radix-to-base (the folder name in the repo)
Moves from: Radix UI (shadcn wrappers and hand-rolled Radix code) to @base-ui/react
Reports: One .migration/<component>.md per component, plus .migration/project.md for a whole-project run

What it includes

npx shadcn@latest info --json, package manager, clean git tree, baseline build
Requires a clean tree, a branch and one commit per component. Installs @base-ui/react next to Radix.
Try: “Migrate the accordion component from Radix to Base UI.”
Runs code · Preflight
Uses the shadcn CLI and registry to get the Base UI version of a wrapper
Whole-project mode: pristine wrappers get shadcn add <component> --overwrite, one component at a time. Progressive mode never uses --overwrite and writes the Base UI version to <component>-base.tsx. Customised wrappers are three-way merged with git merge-file.
Runs code · Golden pair via the CLI
grep for radix-ui and IconPlaceholder in every migrated file
Mandatory even when a merge reported no conflicts.
Leftover sweep
new-york, new-york-v4 and default are classified only, not replayed
Keeps your own classes; flags that the style name will still make the CLI add Radix variants.
Legacy styles
Hand-rolled or unknown-style code is rewritten from the reference tables
Covers imports in both forms, asChild to render, and Portal, Positioner and Popup parts.
Transformation engine
Migrates one component to a -base.tsx file, then repoints consumers one by one
At the end it deletes the original, renames, and flips components.json to base-<style> after the last component.
Progressive mode (default)
Only on request: every wrapper in dependency order, then app code, then drop Radix
Ends with a full build compared with the baseline.
Whole project mode
Never touches cmdk, vaul, sonner, input-otp, react-day-picker or recharts
Behaviour changes are flagged, never silently patched. Skipped files are listed as flagged.
Hard rules
Writes one report per component with Changed, Left alone, Behavior changes, Verify by hand
A whole-project run also writes .migration/project.md. Status is derived from disk.
Write · .migration/ reports
Nine files of mappings for props, classes, menus, overlays, forms and wrapper shapes
class-mapping, consumer-props, disclosure, display-misc, form-controls, menus, overlays, universal-patterns, wrapper-shapes.
Reference guides

From the official docs

Permissions

Medium risk

Claude edits many files, installs and removes packages, runs the shadcn CLI and makes git commits. Start from a clean branch and review each commit.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It rewrites many files and dependencies
The migration edits wrappers and call sites, installs @base-ui/react and removes Radix packages at the end. Run it on a clean branch and review each commit. github.com
It can overwrite your wrappers in whole-project mode
Only in a whole-project run, pristine wrappers get shadcn add <component> --overwrite, one component at a time. The default progressive mode writes <component>-base.tsx beside the original and does not use --overwrite. Customised files are merged instead. Check that files it calls pristine really are. github.com
It runs the latest shadcn CLI
Preflight runs npx shadcn@latest info --json, and it fetches component definitions from ui.shadcn.com. That is third-party code and network access. github.com
Behaviour can change without compile errors
Tabs activation, menu close-on-click and navigation menu delays can differ. The skill flags them and lists a Verify by hand checklist per component; do the clicking. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	SKILL.md defines no read-only mode. It requires a clean git tree and a branch, so your changes can be reviewed or discarded.
Talks to	shadcn CLI and registry requests. Fetches component definitions from ui.shadcn.com. Package manager downloads
Sign-in and keys	SKILL.md names no credentials or sign-in.
Scopes	Claude edits many component and app files Claude installs @base-ui/react and, at the end, removes Radix packages Claude runs npx shadcn@latest commands and makes git commits on a branch Claude writes .migration/ reports in your project

Questions

What does the migrate-radix-to-base skill do?

It makes Claude move a React project, or one component, from Radix UI to Base UI (@base-ui/react), including shadcn wrappers and the code that uses them, while keeping the project buildable at each step.

How do I install it?

Use the install box at the top of this page. Then ask Claude to migrate a component, for example the accordion. The skill is part of the shadcn/ui repo under skills/migrate-radix-to-base.

Does it migrate my whole project at once?

Not by default. The default is progressive: one component at a time into a -base.tsx file, with consumers repointed one by one. Whole-project mode runs only when you explicitly ask for it.

Will it change how my app looks?

For shadcn styles named radix-<style> it fetches the Base UI version of the same style and replays your customisations onto it. For legacy styles such as new-york it keeps your own classes. Behaviour differences, such as tabs activation or menus closing on click, are flagged rather than patched.

Does it touch cmdk, vaul or sonner?

No. A hard rule says never to touch non-Radix libraries such as cmdk (command), vaul (drawer), sonner, input-otp, react-day-picker and recharts. They are reported as intentionally untouched.

How do I check what is left to migrate?

Ask Claude what is left. Status comes from the disk: it scans your ui folder for remaining Radix imports and ends each run with a count of wrappers still on Radix.

Is it safe to run?

It edits many source files, installs packages, runs shadcn CLI commands and makes git commits, so use a branch. The skill itself requires a clean git tree, one commit per component and a baseline build before it starts.

Information

updated Nov 2, 2026

Repository: shadcn/ui
Folder: skills/migrate-radix-to-base

shadcn/ui skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 2

migrate-radix-to-base SKILL.md · github.com
skills.sh listing · skills.sh