Shadcn UI

1---
2name: shadcn-ui
3description: Expert guidance for integrating and building applications with shadcn/ui components, including component discovery, installation, customization, and best practices.
4allowed-tools:
5  - "shadcn*:*"
6  - "mcp_shadcn*"
7  - "Read"
8  - "Write"
9  - "Bash"
10  - "web_fetch"
11---
12 
13# shadcn/ui Component Integration
14 
15You are a frontend engineer specialized in building applications with shadcn/ui—a collection of beautifully designed, accessible, and customizable components built with Radix UI or Base UI and Tailwind CSS. You help developers discover, integrate, and customize components following best practices.
16 
17## Core Principles
18 
19shadcn/ui is **not a component library**—it's a collection of reusable components that you copy into your project. This gives you:
20- **Full ownership**: Components live in your codebase, not node_modules
21- **Complete customization**: Modify styling, behavior, and structure freely, including choosing between Radix UI or Base UI primitives
22- **No version lock-in**: Update components selectively at your own pace
23- **Zero runtime overhead**: No library bundle, just the code you need
24 
25## Component Discovery and Installation
26 
27### 1. Browse Available Components
28 
29Use the shadcn MCP tools to explore the component catalog and Registry Directory:
30- **List all components**: Use `list_components` to see the complete catalog
31- **Get component metadata**: Use `get_component_metadata` to understand props, dependencies, and usage
32- **View component demos**: Use `get_component_demo` to see implementation examples
33 
34### 2. Component Installation
35 
36There are two approaches to adding components:
37 
38**A. Direct Installation (Recommended)**
39```bash
40npx shadcn@latest add [component-name]
41```
42 
43This command:
44- Downloads the component source code (adapting to your config: Radix vs Base UI)
45- Installs required dependencies
46- Places files in `components/ui/`
47- Updates your `components.json` config
48 
49**B. Manual Integration**
501. Use `get_component` to retrieve the source code
512. Create the file in `components/ui/[component-name].tsx`
523. Install peer dependencies manually
534. Adjust imports if needed
54 
55### 3. Registry and Custom Registries
56 
57If working with a custom registry (defined in `components.json`) or exploring the Registry Directory:
58- Use `get_project_registries` to list available registries
59- Use `list_items_in_registries` to see registry-specific components
60- Use `view_items_in_registries` for detailed component information
61- Use `search_items_in_registries` to find specific components
62 
63## Project Setup
64 
65### Initial Configuration
66 
67For **new projects**, use the `create` command to customize everything (style, fonts, component library):
68 
69```bash
70npx shadcn@latest create
71```
72 
73For **existing projects**, initialize configuration:
74 
75```bash
76npx shadcn@latest init
77```
78 
79This creates `components.json` with your configuration:
80- **style**: default, new-york (classic) OR choose new visual styles like Vega, Nova, Maia, Lyra, Mira
81- **baseColor**: slate, gray, zinc, neutral, stone
82- **cssVariables**: true/false for CSS variable usage
83- **tailwind config**: paths to Tailwind files
84- **aliases**: import path shortcuts
85- **rsc**: Use React Server Components (yes/no)
86- **rtl**: Enable RTL support (optional)
87 
88### Required Dependencies
89 
90shadcn/ui components require:
91- **React** (18+)
92- **Tailwind CSS** (3.0+)
93- **Primitives**: Radix UI OR Base UI (depending on your choice)
94- **class-variance-authority** (for variant styling)
95- **clsx** and **tailwind-merge** (for class composition)
96 
97## Component Architecture
98 
99### File Structure
100```
101src/
102├── components/
103│   ├── ui/              # shadcn components
104│   │   ├── button.tsx
105│   │   ├── card.tsx
106│   │   └── dialog.tsx
107│   └── [custom]/        # your composed components
108│       └── user-card.tsx
109├── lib/
110│   └── utils.ts         # cn() utility
111└── app/
112    └── page.tsx
113```
114 
115### The `cn()` Utility
116 
117All shadcn components use the `cn()` helper for class merging:
118 
119```typescript
120import { clsx, type ClassValue } from "clsx"
121import { twMerge } from "tailwind-merge"
122 
123export function cn(...inputs: ClassValue[]) {
124  return twMerge(clsx(inputs))
125}
126```
127 
128This allows you to:
129- Override default styles without conflicts
130- Conditionally apply classes
131- Merge Tailwind classes intelligently
132 
133## Customization Best Practices
134 
135### 1. Theme Customization
136 
137Edit your Tailwind config and CSS variables in `app/globals.css`:
138 
139```css
140@layer base {
141  :root {
142    --background: 0 0% 100%;
143    --foreground: 222.2 84% 4.9%;
144    --primary: 221.2 83.2% 53.3%;
145    /* ... more variables */
146  }
147  
148  .dark {
149    --background: 222.2 84% 4.9%;
150    --foreground: 210 40% 98%;
151    /* ... dark mode overrides */
152  }
153}
154```
155 
156### 2. Component Variants
157 
158Use `class-variance-authority` (cva) for variant logic:
159 
160```typescript
161import { cva } from "class-variance-authority"
162 
163const buttonVariants = cva(
164  "inline-flex items-center justify-center rounded-md",
165  {
166    variants: {
167      variant: {
168        default: "bg-primary text-primary-foreground",
169        outline: "border border-input",
170      },
171      size: {
172        default: "h-10 px-4 py-2",
173        sm: "h-9 rounded-md px-3",
174      },
175    },
176    defaultVariants: {
177      variant: "default",
178      size: "default",
179    },
180  }
181)
182```
183 
184### 3. Extending Components
185 
186Create wrapper components in `components/` (not `components/ui/`):
187 
188```typescript
189// components/custom-button.tsx
190import { Button } from "@/components/ui/button"
191import { Loader2 } from "lucide-react"
192 
193export function LoadingButton({ 
194  loading, 
195  children, 
196  ...props 
197}: ButtonProps & { loading?: boolean }) {
198  return (
199    <Button disabled={loading} {...props}>
200      {loading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
201      {children}
202    </Button>
203  )
204}
205```
206 
207## Blocks and Complex Components
208 
209shadcn/ui provides complete UI blocks (authentication forms, dashboards, etc.):
210 
2111. **List available blocks**: Use `list_blocks` with optional category filter
2122. **Get block source**: Use `get_block` with the block name
2133. **Install blocks**: Many blocks include multiple component files
214 
215Blocks are organized by category:
216- **calendar**: Calendar interfaces
217- **dashboard**: Dashboard layouts
218- **login**: Authentication flows
219- **sidebar**: Navigation sidebars
220- **products**: E-commerce components
221 
222## Accessibility
223 
224All shadcn/ui components are built on Radix UI primitives, ensuring:
225- **Keyboard navigation**: Full keyboard support out of the box
226- **Screen reader support**: Proper ARIA attributes
227- **Focus management**: Logical focus flow
228- **Disabled states**: Proper disabled and aria-disabled handling
229 
230When customizing, maintain accessibility:
231- Keep ARIA attributes
232- Preserve keyboard handlers
233- Test with screen readers
234- Maintain focus indicators
235 
236## Common Patterns
237 
238### Form Building
239```typescript
240import { Button } from "@/components/ui/button"
241import { Input } from "@/components/ui/input"
242import { Label } from "@/components/ui/label"
243 
244// Use with react-hook-form for validation
245import { useForm } from "react-hook-form"
246```
247 
248### Dialog/Modal Patterns
249```typescript
250import {
251  Dialog,
252  DialogContent,
253  DialogDescription,
254  DialogHeader,
255  DialogTitle,
256  DialogTrigger,
257} from "@/components/ui/dialog"
258```
259 
260### Data Display
261```typescript
262import {
263  Table,
264  TableBody,
265  TableCell,
266  TableHead,
267  TableHeader,
268  TableRow,
269} from "@/components/ui/table"
270```
271 
272## Troubleshooting
273 
274### Import Errors
275- Check `components.json` for correct alias configuration
276- Verify `tsconfig.json` includes the `@` path alias:
277  ```json
278  {
279    "compilerOptions": {
280      "paths": {
281        "@/*": ["./src/*"]
282      }
283    }
284  }
285  ```
286 
287### Style Conflicts
288- Ensure Tailwind CSS is properly configured
289- Check that `globals.css` is imported in your root layout
290- Verify CSS variable names match between components and theme
291 
292### Missing Dependencies
293- Run component installation via CLI to auto-install deps
294- Manually check `package.json` for required Radix UI packages
295- Use `get_component_metadata` to see dependency lists
296 
297### Version Compatibility
298- shadcn/ui v4 requires React 18+ and Next.js 13+ (if using Next.js)
299- Some components require specific Radix UI versions
300- Check documentation for breaking changes between versions
301 
302## Validation and Quality
303 
304Before committing components:
3051. **Type check**: Run `tsc --noEmit` to verify TypeScript
3062. **Lint**: Run your linter to catch style issues
3073. **Test accessibility**: Use tools like axe DevTools
3084. **Visual QA**: Test in light and dark modes
3095. **Responsive check**: Verify behavior at different breakpoints
310 
311## Resources
312 
313Refer to the following resource files for detailed guidance:
314- `resources/setup-guide.md` - Step-by-step project initialization
315- `resources/component-catalog.md` - Complete component reference
316- `resources/customization-guide.md` - Theming and variant patterns
317- `resources/migration-guide.md` - Upgrading from other UI libraries
318 
319## Examples
320 
321See the `examples/` directory for:
322- Complete component implementations
323- Form patterns with validation
324- Dashboard layouts
325- Authentication flows
326- Data table implementations
327