1# Migration Guide to shadcn/ui
2 
3This guide helps you migrate from other UI libraries to shadcn/ui.
4 
5## Why Migrate to shadcn/ui?
6 
7- **Full ownership**: Code lives in your project, not node_modules
8- **Customizable**: Modify any component to fit your needs
9- **No breaking changes**: Update components individually
10- **Smaller bundles**: Only include what you use
11- **Modern stack**: Built with Radix UI and Tailwind CSS
12- **Type-safe**: Full TypeScript support
13 
14## Migration Strategies
15 
16### Strategy 1: Incremental Migration (Recommended)
17 
18Gradually replace components over time:
19 
201. Install shadcn/ui alongside existing library
212. Replace components page by page or feature by feature
223. Remove old library once migration is complete
23 
24**Pros**: Low risk, can be done alongside feature work
25**Cons**: Temporary bundle size increase
26 
27### Strategy 2: Big Bang Migration
28 
29Replace all components at once:
30 
311. Set up shadcn/ui
322. Create component mapping document
333. Replace all components in one effort
344. Test thoroughly
35 
36**Pros**: Clean cutover, no mixed UI
37**Cons**: High risk, requires dedicated time
38 
39## Internal Migrations (shadcn specific)
40 
41### RTL Support Migration
42If you need to support RTL languages (like Arabic or Hebrew) in an existing shadcn/ui project:
43 
44```bash
45npx shadcn@latest migrate rtl
46```
47 
48This CLI command transforms your components to use **logical properties**:
49- `ml-4` -> `ms-4` (margin-start)
50- `pl-4` -> `ps-4` (padding-start)
51- `text-left` -> `text-start`
52 
53It ensures your UI adapts correctly to layout direction without manual refactoring.
54 
55## From Material-UI (MUI)
56 
57### Component Mapping
58 
59| MUI Component | shadcn/ui Equivalent | Notes |
60|---------------|----------------------|-------|
61| Button | Button | Similar API |
62| TextField | Input + Label | Separate components |
63| Select | Select | Different structure |
64| Dialog | Dialog | Similar concept |
65| Drawer | Sheet | Side panel |
66| Card | Card | Very similar |
67| Table | Table | Use with TanStack Table |
68| Checkbox | Checkbox | Similar API |
69| Switch | Switch | Similar API |
70| Tabs | Tabs | Similar structure |
71| Tooltip | Tooltip | Simpler API |
72| Menu | Dropdown Menu | Different trigger model |
73| Snackbar | Toast | Different implementation |
74| Autocomplete | Combobox | Use with Command |
75 
76### Key Differences
77 
78**1. Import Structure**
79```tsx
80// MUI
81import Button from '@mui/material/Button'
82 
83// shadcn/ui
84import { Button } from '@/components/ui/button'
85```
86 
87**2. Form Components**
88```tsx
89// MUI
90<TextField
91  label="Email"
92  value={email}
93  onChange={(e) => setEmail(e.target.value)}
94  error={!!errors.email}
95  helperText={errors.email}
96/>
97 
98// shadcn/ui
99<div className="space-y-2">
100  <Label htmlFor="email">Email</Label>
101  <Input
102    id="email"
103    value={email}
104    onChange={(e) => setEmail(e.target.value)}
105  />
106  {errors.email && (
107    <p className="text-sm text-destructive">{errors.email}</p>
108  )}
109</div>
110 
111// Or with Form component
112<FormField
113  control={form.control}
114  name="email"
115  render={({ field }) => (
116    <FormItem>
117      <FormLabel>Email</FormLabel>
118      <FormControl>
119        <Input {...field} />
120      </FormControl>
121      <FormMessage />
122    </FormItem>
123  )}
124/>
125```
126 
127**3. Theming**
128```tsx
129// MUI
130import { ThemeProvider, createTheme } from '@mui/material/styles'
131 
132const theme = createTheme({
133  palette: {
134    primary: { main: '#1976d2' },
135  },
136})
137 
138<ThemeProvider theme={theme}>
139  <App />
140</ThemeProvider>
141 
142// shadcn/ui
143// Edit globals.css
144:root {
145  --primary: 215 100% 50%;
146}
147```
148 
149**4. Styling Approach**
150```tsx
151// MUI (sx prop)
152<Button sx={{ px: 4, py: 2, borderRadius: 2 }}>
153  Click me
154</Button>
155 
156// shadcn/ui (Tailwind classes)
157<Button className="px-4 py-2 rounded-lg">
158  Click me
159</Button>
160```
161 
162### Migration Example: Login Form
163 
164**Before (MUI)**:
165```tsx
166import { TextField, Button, Box } from '@mui/material'
167 
168export function LoginForm() {
169  return (
170    <Box component="form" sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
171      <TextField label="Email" type="email" required />
172      <TextField label="Password" type="password" required />
173      <Button variant="contained" type="submit">
174        Sign In
175      </Button>
176    </Box>
177  )
178}
179```
180 
181**After (shadcn/ui)**:
182```tsx
183import { Input } from '@/components/ui/input'
184import { Label } from '@/components/ui/label'
185import { Button } from '@/components/ui/button'
186 
187export function LoginForm() {
188  return (
189    <form className="flex flex-col gap-4">
190      <div className="space-y-2">
191        <Label htmlFor="email">Email</Label>
192        <Input id="email" type="email" required />
193      </div>
194      <div className="space-y-2">
195        <Label htmlFor="password">Password</Label>
196        <Input id="password" type="password" required />
197      </div>
198      <Button type="submit">Sign In</Button>
199    </form>
200  )
201}
202```
203 
204## From Chakra UI
205 
206### Component Mapping
207 
208| Chakra UI | shadcn/ui | Notes |
209|-----------|-----------|-------|
210| Button | Button | Similar variants |
211| Input | Input | More basic |
212| Select | Select | Different structure |
213| Modal | Dialog | Similar concept |
214| Drawer | Sheet | Very similar |
215| Box | div | Use Tailwind classes |
216| Flex | div | Use flex utilities |
217| Stack | div | Use space-y-* classes |
218| Text | p/span | Use typography classes |
219| Heading | h1/h2/etc | Use typography classes |
220| useToast | useToast | Different API |
221| Menu | Dropdown Menu | Similar |
222 
223### Key Differences
224 
225**1. Layout Components**
226```tsx
227// Chakra UI
228<Stack spacing={4} direction="column">
229  <Box>Item 1</Box>
230  <Box>Item 2</Box>
231</Stack>
232 
233// shadcn/ui
234<div className="flex flex-col space-y-4">
235  <div>Item 1</div>
236  <div>Item 2</div>
237</div>
238```
239 
240**2. Responsive Styles**
241```tsx
242// Chakra UI
243<Box display={{ base: 'block', md: 'flex' }} />
244 
245// shadcn/ui
246<div className="block md:flex" />
247```
248 
249**3. Color Mode**
250```tsx
251// Chakra UI
252import { useColorMode } from '@chakra-ui/react'
253 
254const { colorMode, toggleColorMode } = useColorMode()
255 
256// shadcn/ui (with next-themes)
257import { useTheme } from 'next-themes'
258 
259const { theme, setTheme } = useTheme()
260```
261 
262## From Ant Design
263 
264### Component Mapping
265 
266| Ant Design | shadcn/ui | Notes |
267|------------|-----------|-------|
268| Button | Button | Similar |
269| Input | Input | More basic |
270| Form | Form | Different approach |
271| Table | Table | Use TanStack Table |
272| Modal | Dialog | Similar |
273| Drawer | Sheet | Similar |
274| Select | Select | Different API |
275| DatePicker | Calendar + Popover | More manual |
276| Menu | Navigation Menu | Different |
277| message | Toast | Different API |
278| notification | Toast | Similar concept |
279 
280### Key Differences
281 
282**1. Form Handling**
283```tsx
284// Ant Design
285<Form
286  form={form}
287  onFinish={onSubmit}
288>
289  <Form.Item name="email" rules={[{ required: true }]}>
290    <Input />
291  </Form.Item>
292  <Form.Item>
293    <Button type="primary" htmlType="submit">Submit</Button>
294  </Form.Item>
295</Form>
296 
297// shadcn/ui (with react-hook-form)
298<Form {...form}>
299  <form onSubmit={form.handleSubmit(onSubmit)}>
300    <FormField
301      control={form.control}
302      name="email"
303      render={({ field }) => (
304        <FormItem>
305          <FormControl>
306            <Input {...field} />
307          </FormControl>
308          <FormMessage />
309        </FormItem>
310      )}
311    />
312    <Button type="submit">Submit</Button>
313  </form>
314</Form>
315```
316 
317**2. Notifications**
318```tsx
319// Ant Design
320import { message } from 'antd'
321 
322message.success('Success!')
323 
324// shadcn/ui
325import { useToast } from '@/components/ui/use-toast'
326 
327const { toast } = useToast()
328 
329toast({
330  title: "Success!",
331  description: "Operation completed.",
332})
333```
334 
335## From Bootstrap
336 
337### Component Mapping
338 
339| Bootstrap | shadcn/ui | Notes |
340|-----------|-----------|-------|
341| btn | Button | Similar variants |
342| form-control | Input | Similar |
343| card | Card | Very similar structure |
344| modal | Dialog | Different API |
345| dropdown | Dropdown Menu | Similar concept |
346| nav/navbar | Navigation Menu | Different |
347| alert | Alert | Similar |
348| badge | Badge | Similar |
349| table | Table | Use with TanStack Table |
350 
351### Key Differences
352 
353**1. Class-Based vs Component-Based**
354```tsx
355// Bootstrap
356<button className="btn btn-primary btn-lg">
357  Click me
358</button>
359 
360// shadcn/ui
361<Button variant="default" size="lg">
362  Click me
363</Button>
364```
365 
366**2. Cards**
367```html
368<!-- Bootstrap -->
369<div class="card">
370  <div class="card-header">Title</div>
371  <div class="card-body">Content</div>
372  <div class="card-footer">Footer</div>
373</div>
374 
375<!-- shadcn/ui -->
376<Card>
377  <CardHeader>
378    <CardTitle>Title</CardTitle>
379  </CardHeader>
380  <CardContent>Content</CardContent>
381  <CardFooter>Footer</CardFooter>
382</Card>
383```
384 
385## Migration Checklist
386 
387### Before Migration
388 
389- [ ] Audit current component usage
390- [ ] Set up shadcn/ui in a test branch
391- [ ] Create component mapping document
392- [ ] Plan migration order (start with simple components)
393- [ ] Set up Tailwind CSS properly
394- [ ] Configure path aliases
395 
396### During Migration
397 
398- [ ] Install shadcn/ui components as needed
399- [ ] Replace components incrementally
400- [ ] Update styling to use Tailwind classes
401- [ ] Test each page/feature after migration
402- [ ] Update tests to match new components
403- [ ] Handle form validation (switch to react-hook-form + zod)
404- [ ] Migrate theme/color variables
405 
406### After Migration
407 
408- [ ] Remove old UI library dependencies
409- [ ] Clean up unused imports
410- [ ] Optimize bundle size
411- [ ] Update documentation
412- [ ] Review and update design system
413- [ ] Train team on new components
414 
415## Common Pitfalls
416 
417### 1. Not Setting Up Tailwind Properly
418 
419shadcn/ui requires Tailwind. Ensure:
420- `tailwind.config.js` includes correct content paths
421- CSS variables are defined in `globals.css`
422- Tailwind plugins are installed (e.g., `tailwindcss-animate`)
423 
424### 2. Forgetting Path Aliases
425 
426Components use `@/` imports. Configure:
427- `tsconfig.json` with path aliases
428- Vite/Next.js config for runtime resolution
429 
430### 3. Trying to Match Old Library Exactly
431 
432Don't force shadcn/ui to work like your old library. Embrace the new patterns:
433- Use composition over configuration
434- Leverage Tailwind utilities
435- Create wrapper components for custom needs
436 
437### 4. Not Using Form Libraries
438 
439shadcn/ui form components are basic. For complex forms, use:
440- `react-hook-form` for form state
441- `zod` for validation
442- shadcn's `Form` component for integration
443 
444### 5. Ignoring Accessibility
445 
446While shadcn/ui is accessible by default, custom modifications can break this. Test with:
447- Keyboard navigation
448- Screen readers
449- ARIA attribute validation
450 
451## Getting Help
452 
453- **Discord**: [shadcn/ui Discord](https://discord.com/invite/vNvTqVaWm6)
454- **GitHub Discussions**: [shadcn/ui Discussions](https://github.com/shadcn-ui/ui/discussions)
455- **Documentation**: [ui.shadcn.com](https://ui.shadcn.com)
456 
457## Next Steps
458 
459After migration:
4601. Review the [Customization Guide](./customization-guide.md)
4612. Explore the [Component Catalog](./component-catalog.md)
4623. Check out [Examples](../examples/)
4634. Consider building a component library on top of shadcn/ui
464