1# shadcn/ui Learning Guide
2 
3This guide helps you learn shadcn/ui from basics to advanced patterns.
4 
5## Learning Path
6 
7### 1. Understanding the Philosophy
8 
9shadcn/ui is different from traditional component libraries:
10 
11- **Copy-paste components**: Components are copied into your project, not installed as packages
12- **Full customization**: You own the code and can modify it freely
13- **Built on Radix UI**: Provides accessibility primitives
14- **Styled with Tailwind**: Uses utility classes for consistent styling
15 
16### 2. Core Concepts to Master
17 
18#### Class Variance Authority (CVA)
19Most components use CVA for variant management:
20 
21```tsx
22const buttonVariants = cva(
23  "base-classes",
24  {
25    variants: {
26      variant: {
27        default: "variant-classes",
28        destructive: "destructive-classes",
29      },
30      size: {
31        default: "size-classes",
32        sm: "small-classes",
33      },
34    },
35    defaultVariants: {
36      variant: "default",
37      size: "default",
38    },
39  }
40)
41```
42 
43#### cn Utility Function
44The `cn` function combines classes and resolves conflicts:
45 
46```tsx
47import { clsx, type ClassValue } from "clsx"
48import { twMerge } from "tailwind-merge"
49 
50export function cn(...inputs: ClassValue[]) {
51  return twMerge(clsx(inputs))
52}
53```
54 
55### 3. Installation Checklist
56 
57- [ ] Initialize a new project (Next.js, Vite, or Remix)
58- [ ] Install Tailwind CSS
59- [ ] Run `npx shadcn@latest init`
60- [ ] Configure CSS variables
61- [ ] Install first component: `npx shadcn@latest add button`
62 
63### 4. Essential Components to Learn First
64 
651. **Button** - Learn variants and sizes
662. **Input** - Form inputs with labels
673. **Card** - Container components
684. **Form** - Form handling with React Hook Form
695. **Dialog** - Modal windows
706. **Select** - Dropdown selections
717. **Toast** - Notifications
72 
73### 5. Common Patterns
74 
75#### Form Pattern
76Every form follows this structure:
77 
78```tsx
791. Define Zod schema
802. Create form with useForm
813. Wrap with Form component
824. Add FormField for each input
835. Handle submission
84```
85 
86#### Component Customization Pattern
87To customize a component:
88 
891. Copy component to your project
902. Modify the variants
913. Add new props if needed
924. Update types
93 
94### 6. Best Practices
95 
96- Always use TypeScript
97- Follow the existing component structure
98- Use semantic HTML when possible
99- Test with screen readers for accessibility
100- Keep components small and focused
101 
102### 7. Advanced Topics
103 
104- Creating custom components from scratch
105- Building complex forms with validation
106- Implementing dark mode
107- Optimizing for performance
108- Testing components
109 
110## Practice Exercises
111 
112### Exercise 1: Basic Setup
1131. Create a new Next.js project
1142. Set up shadcn/ui
1153. Install and customize a Button component
1164. Add a new variant "gradient"
117 
118### Exercise 2: Form Building
1191. Create a contact form with:
120   - Name input (required)
121   - Email input (email validation)
122   - Message textarea (min length)
123   - Submit button with loading state
124 
125### Exercise 3: Component Combination
1261. Build a settings page using:
127   - Card for layout
128   - Sheet for mobile menu
129   - Select for dropdowns
130   - Switch for toggles
131   - Toast for notifications
132 
133### Exercise 4: Custom Component
1341. Create a custom Badge component
1352. Support variants: default, secondary, destructive, outline
1363. Support sizes: sm, default, lg
1374. Add icon support
138 
139## Resources
140 
141- [Official Documentation](https://ui.shadcn.com)
142- [GitHub Repository](https://github.com/shadcn/ui)
143- [Examples Gallery](https://ui.shadcn.com/examples)
144- [Radix UI Primitives](https://www.radix-ui.com/primitives)
145- [Tailwind CSS Documentation](https://tailwindcss.com/docs)