Migrating from shadcn/ui to Rad UI

shadcn/ui copies Radix-based component files into your repo and styles them with Tailwind. Rad UI is a package you install: the same compound-part model (Root, Trigger, Content, asChild, data-state), with the components maintained for you and three ways to style them. Most screens move over by changing imports and part names, one component at a time.

Why teams switch

  • No copied code to maintain. Fixes and new components arrive with npm update instead of re-running a generator and merging by hand.
  • Styling is your choice. Use the Clarity theme, the Tailwind preset, or style the data-* attributes yourself.
  • Same mental model. If you know shadcn's Dialog, you already know Rad UI's: parts, asChild, and state on the element.

If you're still deciding, see Rad UI vs shadcn/ui.

1. Install

Terminal
npm install @radui/ui

2. Pick how you'll style it

PathPick it whenSetup
Tailwind presetYou're on Tailwind, as most shadcn apps are@import "@radui/ui/themes/tailwind-presets/default.css" after tailwindcss in your global CSS
Clarity themeYou want finished-looking components nowimport "@radui/ui/themes/default.css" and wrap the app in Theme classNamespace="rad-ui"
HeadlessYou'll keep your own lookNothing: style the parts and their data-* attributes with any CSS

Details: Installation and Styling and customization.

3. Move one component at a time

shadcn components and Rad UI components work side by side, so you don't need a big-bang rewrite. A good order: leaf components first (Button, Badge, Avatar, Separator), then form controls (Checkbox, Switch, Select), then overlays (Dialog, Popover, DropdownMenu, Tooltip). Delete each components/ui/*.tsx file once nothing imports it.

Before and after: Dialog

shadcn/ui:

React
import { Button } from "@/components/ui/button"; import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger, DialogClose, } from "@/components/ui/dialog"; <Dialog> <DialogTrigger asChild> <Button variant="outline">Edit profile</Button> </DialogTrigger> <DialogContent> <DialogHeader> <DialogTitle>Edit profile</DialogTitle> <DialogDescription>Make changes to your profile.</DialogDescription> </DialogHeader> {/* form */} <DialogFooter> <DialogClose asChild><Button>Save</Button></DialogClose> </DialogFooter> </DialogContent> </Dialog>

Rad UI:

React
import Button from "@radui/ui/Button"; import Dialog from "@radui/ui/Dialog"; <Dialog.Root> <Dialog.Trigger asChild> <Button variant="outline">Edit profile</Button> </Dialog.Trigger> <Dialog.Portal> <Dialog.Overlay /> <Dialog.Content> <Dialog.Title>Edit profile</Dialog.Title> <Dialog.Description>Make changes to your profile.</Dialog.Description> {/* form */} <Dialog.Footer> <Dialog.Close asChild><Button>Save</Button></Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog.Portal> </Dialog.Root>

What changed: one import per component, parts are properties (Dialog.Title instead of DialogTitle), and the portal and overlay are explicit parts you can style or leave out. shadcn's DialogHeader is a styled div; use your own wrapper or none.

Component map

shadcn/uiRad UIParts
AccordionAccordionRoot, Item, Header, Trigger, Content
Alert DialogAlertDialogRoot, Trigger, Portal, Overlay, Content, Title, Description, Footer, Cancel, Action
AvatarAvatarRoot, Image, Fallback
BadgeBadgesingle component
BreadcrumbBreadcrumbsee its page
ButtonButtonsingle component, variant and size props
CardCardRoot, Header, Title, Description, Action, Content, Footer
CheckboxCheckboxRoot, Indicator
CollapsibleCollapsiblesee its page
CommandCommandin preview
Context MenuContextMenusee its page
DialogDialogRoot, Trigger, Portal, Overlay, Content, Title, Description, Footer, Close
Dropdown MenuDropdownMenuRoot, Trigger, Portal, Content, Item, Group, GroupLabel, Separator, CheckboxItem, RadioGroup, RadioItem, ItemIndicator, Sub, SubTrigger, Arrow
Hover CardHoverCardsee its page
InputTextFieldsee its page
Input OTPOTPFieldsee its page
LabelLabelsingle component
MenubarMenubarsee its page
Navigation MenuNavigationMenusee its page
PopoverPopoverRoot, Trigger, Anchor, Portal, Content, Title, Description, Close, Arrow
ProgressProgresssee its page
Radio GroupRadioGroupRoot, Item, Indicator, Label
ResizableSplittersee its page
Scroll AreaScrollAreasee its page
SelectSelectRoot, Trigger, Value, Icon, Portal, Content, Group, GroupLabel, Item, Indicator, Separator, Label, ScrollUpArrow, ScrollDownArrow
SeparatorSeparatorsingle component
SheetDrawersee its page
SkeletonSkeletonsingle component
SliderSliderRoot, Track, Range, Thumb, Marks, Value, plus RangeSlider
Sonner / ToastToastProvider, Viewport, Root, Title, Description, Action, Close
SwitchSwitchRoot, Thumb
TableTableRoot, Head, Body, Row, ColumnCellHeader, Cell
TabsTabsRoot, List, Trigger, Content, Indicator
TextareaTextAreasee its page
ToggleTogglesingle component
Toggle GroupToggleGroupRoot, Item
TooltipTooltipProvider, Root, Trigger, Content

Every component is imported from its own path, for example import Select from "@radui/ui/Select". Each component's page in these docs has the full API and examples.

Not one-to-one

  • Form: shadcn's Form wraps react-hook-form. Rad UI has its own Form and Field primitives for labels, descriptions and errors; you can keep react-hook-form for state and render Rad UI fields.
  • Data Table: shadcn's data table is TanStack Table plus its Table component. Keep TanStack for sorting and filtering and render with Rad UI's Table.
  • Calendar, Date Picker, Chart, Carousel, Sidebar, Pagination: no Rad UI equivalent yet. Keep those shadcn components; they work alongside Rad UI. See component coverage.

Restyling

Rad UI parts expose their state the same way Radix does, so most of your Tailwind state variants carry over:

React
<Dialog.Overlay className="fixed inset-0 bg-black/50 data-[state=open]:animate-in" />

Every element with a data-state also gets a boolean attribute (data-open, data-checked), so data-open:opacity-100 works too. className is passed through on every part.

Checklist

  • @radui/ui installed and one styling path set up
  • Components moved one at a time; each old components/ui file deleted when unused
  • Keyboard check on every overlay you moved: Tab, Shift+Tab, Esc, focus returns to the trigger
  • class-variance-authority and tailwind-merge removed if nothing else uses them