327 lines
9.0 KiB
Markdown
327 lines
9.0 KiB
Markdown
---
|
|
name: shadcn-ui
|
|
description: Expert guidance for integrating and building applications with shadcn/ui components, including component discovery, installation, customization, and best practices.
|
|
allowed-tools:
|
|
- "shadcn*:*"
|
|
- "mcp_shadcn*"
|
|
- "Read"
|
|
- "Write"
|
|
- "Bash"
|
|
- "web_fetch"
|
|
---
|
|
|
|
# shadcn/ui Component Integration
|
|
|
|
You 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.
|
|
|
|
## Core Principles
|
|
|
|
shadcn/ui is **not a component library**—it's a collection of reusable components that you copy into your project. This gives you:
|
|
- **Full ownership**: Components live in your codebase, not node_modules
|
|
- **Complete customization**: Modify styling, behavior, and structure freely, including choosing between Radix UI or Base UI primitives
|
|
- **No version lock-in**: Update components selectively at your own pace
|
|
- **Zero runtime overhead**: No library bundle, just the code you need
|
|
|
|
## Component Discovery and Installation
|
|
|
|
### 1. Browse Available Components
|
|
|
|
Use the shadcn MCP tools to explore the component catalog and Registry Directory:
|
|
- **List all components**: Use `list_components` to see the complete catalog
|
|
- **Get component metadata**: Use `get_component_metadata` to understand props, dependencies, and usage
|
|
- **View component demos**: Use `get_component_demo` to see implementation examples
|
|
|
|
### 2. Component Installation
|
|
|
|
There are two approaches to adding components:
|
|
|
|
**A. Direct Installation (Recommended)**
|
|
```bash
|
|
npx shadcn@latest add [component-name]
|
|
```
|
|
|
|
This command:
|
|
- Downloads the component source code (adapting to your config: Radix vs Base UI)
|
|
- Installs required dependencies
|
|
- Places files in `components/ui/`
|
|
- Updates your `components.json` config
|
|
|
|
**B. Manual Integration**
|
|
1. Use `get_component` to retrieve the source code
|
|
2. Create the file in `components/ui/[component-name].tsx`
|
|
3. Install peer dependencies manually
|
|
4. Adjust imports if needed
|
|
|
|
### 3. Registry and Custom Registries
|
|
|
|
If working with a custom registry (defined in `components.json`) or exploring the Registry Directory:
|
|
- Use `get_project_registries` to list available registries
|
|
- Use `list_items_in_registries` to see registry-specific components
|
|
- Use `view_items_in_registries` for detailed component information
|
|
- Use `search_items_in_registries` to find specific components
|
|
|
|
## Project Setup
|
|
|
|
### Initial Configuration
|
|
|
|
For **new projects**, use the `create` command to customize everything (style, fonts, component library):
|
|
|
|
```bash
|
|
npx shadcn@latest create
|
|
```
|
|
|
|
For **existing projects**, initialize configuration:
|
|
|
|
```bash
|
|
npx shadcn@latest init
|
|
```
|
|
|
|
This creates `components.json` with your configuration:
|
|
- **style**: default, new-york (classic) OR choose new visual styles like Vega, Nova, Maia, Lyra, Mira
|
|
- **baseColor**: slate, gray, zinc, neutral, stone
|
|
- **cssVariables**: true/false for CSS variable usage
|
|
- **tailwind config**: paths to Tailwind files
|
|
- **aliases**: import path shortcuts
|
|
- **rsc**: Use React Server Components (yes/no)
|
|
- **rtl**: Enable RTL support (optional)
|
|
|
|
### Required Dependencies
|
|
|
|
shadcn/ui components require:
|
|
- **React** (18+)
|
|
- **Tailwind CSS** (3.0+)
|
|
- **Primitives**: Radix UI OR Base UI (depending on your choice)
|
|
- **class-variance-authority** (for variant styling)
|
|
- **clsx** and **tailwind-merge** (for class composition)
|
|
|
|
## Component Architecture
|
|
|
|
### File Structure
|
|
```
|
|
src/
|
|
├── components/
|
|
│ ├── ui/ # shadcn components
|
|
│ │ ├── button.tsx
|
|
│ │ ├── card.tsx
|
|
│ │ └── dialog.tsx
|
|
│ └── [custom]/ # your composed components
|
|
│ └── user-card.tsx
|
|
├── lib/
|
|
│ └── utils.ts # cn() utility
|
|
└── app/
|
|
└── page.tsx
|
|
```
|
|
|
|
### The `cn()` Utility
|
|
|
|
All shadcn components use the `cn()` helper for class merging:
|
|
|
|
```typescript
|
|
import { clsx, type ClassValue } from "clsx"
|
|
import { twMerge } from "tailwind-merge"
|
|
|
|
export function cn(...inputs: ClassValue[]) {
|
|
return twMerge(clsx(inputs))
|
|
}
|
|
```
|
|
|
|
This allows you to:
|
|
- Override default styles without conflicts
|
|
- Conditionally apply classes
|
|
- Merge Tailwind classes intelligently
|
|
|
|
## Customization Best Practices
|
|
|
|
### 1. Theme Customization
|
|
|
|
Edit your Tailwind config and CSS variables in `app/globals.css`:
|
|
|
|
```css
|
|
@layer base {
|
|
:root {
|
|
--background: 0 0% 100%;
|
|
--foreground: 222.2 84% 4.9%;
|
|
--primary: 221.2 83.2% 53.3%;
|
|
/* ... more variables */
|
|
}
|
|
|
|
.dark {
|
|
--background: 222.2 84% 4.9%;
|
|
--foreground: 210 40% 98%;
|
|
/* ... dark mode overrides */
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. Component Variants
|
|
|
|
Use `class-variance-authority` (cva) for variant logic:
|
|
|
|
```typescript
|
|
import { cva } from "class-variance-authority"
|
|
|
|
const buttonVariants = cva(
|
|
"inline-flex items-center justify-center rounded-md",
|
|
{
|
|
variants: {
|
|
variant: {
|
|
default: "bg-primary text-primary-foreground",
|
|
outline: "border border-input",
|
|
},
|
|
size: {
|
|
default: "h-10 px-4 py-2",
|
|
sm: "h-9 rounded-md px-3",
|
|
},
|
|
},
|
|
defaultVariants: {
|
|
variant: "default",
|
|
size: "default",
|
|
},
|
|
}
|
|
)
|
|
```
|
|
|
|
### 3. Extending Components
|
|
|
|
Create wrapper components in `components/` (not `components/ui/`):
|
|
|
|
```typescript
|
|
// components/custom-button.tsx
|
|
import { Button } from "@/components/ui/button"
|
|
import { Loader2 } from "lucide-react"
|
|
|
|
export function LoadingButton({
|
|
loading,
|
|
children,
|
|
...props
|
|
}: ButtonProps & { loading?: boolean }) {
|
|
return (
|
|
<Button disabled={loading} {...props}>
|
|
{loading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
|
|
{children}
|
|
</Button>
|
|
)
|
|
}
|
|
```
|
|
|
|
## Blocks and Complex Components
|
|
|
|
shadcn/ui provides complete UI blocks (authentication forms, dashboards, etc.):
|
|
|
|
1. **List available blocks**: Use `list_blocks` with optional category filter
|
|
2. **Get block source**: Use `get_block` with the block name
|
|
3. **Install blocks**: Many blocks include multiple component files
|
|
|
|
Blocks are organized by category:
|
|
- **calendar**: Calendar interfaces
|
|
- **dashboard**: Dashboard layouts
|
|
- **login**: Authentication flows
|
|
- **sidebar**: Navigation sidebars
|
|
- **products**: E-commerce components
|
|
|
|
## Accessibility
|
|
|
|
All shadcn/ui components are built on Radix UI primitives, ensuring:
|
|
- **Keyboard navigation**: Full keyboard support out of the box
|
|
- **Screen reader support**: Proper ARIA attributes
|
|
- **Focus management**: Logical focus flow
|
|
- **Disabled states**: Proper disabled and aria-disabled handling
|
|
|
|
When customizing, maintain accessibility:
|
|
- Keep ARIA attributes
|
|
- Preserve keyboard handlers
|
|
- Test with screen readers
|
|
- Maintain focus indicators
|
|
|
|
## Common Patterns
|
|
|
|
### Form Building
|
|
```typescript
|
|
import { Button } from "@/components/ui/button"
|
|
import { Input } from "@/components/ui/input"
|
|
import { Label } from "@/components/ui/label"
|
|
|
|
// Use with react-hook-form for validation
|
|
import { useForm } from "react-hook-form"
|
|
```
|
|
|
|
### Dialog/Modal Patterns
|
|
```typescript
|
|
import {
|
|
Dialog,
|
|
DialogContent,
|
|
DialogDescription,
|
|
DialogHeader,
|
|
DialogTitle,
|
|
DialogTrigger,
|
|
} from "@/components/ui/dialog"
|
|
```
|
|
|
|
### Data Display
|
|
```typescript
|
|
import {
|
|
Table,
|
|
TableBody,
|
|
TableCell,
|
|
TableHead,
|
|
TableHeader,
|
|
TableRow,
|
|
} from "@/components/ui/table"
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Import Errors
|
|
- Check `components.json` for correct alias configuration
|
|
- Verify `tsconfig.json` includes the `@` path alias:
|
|
```json
|
|
{
|
|
"compilerOptions": {
|
|
"paths": {
|
|
"@/*": ["./src/*"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Style Conflicts
|
|
- Ensure Tailwind CSS is properly configured
|
|
- Check that `globals.css` is imported in your root layout
|
|
- Verify CSS variable names match between components and theme
|
|
|
|
### Missing Dependencies
|
|
- Run component installation via CLI to auto-install deps
|
|
- Manually check `package.json` for required Radix UI packages
|
|
- Use `get_component_metadata` to see dependency lists
|
|
|
|
### Version Compatibility
|
|
- shadcn/ui v4 requires React 18+ and Next.js 13+ (if using Next.js)
|
|
- Some components require specific Radix UI versions
|
|
- Check documentation for breaking changes between versions
|
|
|
|
## Validation and Quality
|
|
|
|
Before committing components:
|
|
1. **Type check**: Run `tsc --noEmit` to verify TypeScript
|
|
2. **Lint**: Run your linter to catch style issues
|
|
3. **Test accessibility**: Use tools like axe DevTools
|
|
4. **Visual QA**: Test in light and dark modes
|
|
5. **Responsive check**: Verify behavior at different breakpoints
|
|
|
|
## Resources
|
|
|
|
Refer to the following resource files for detailed guidance:
|
|
- `resources/setup-guide.md` - Step-by-step project initialization
|
|
- `resources/component-catalog.md` - Complete component reference
|
|
- `resources/customization-guide.md` - Theming and variant patterns
|
|
- `resources/migration-guide.md` - Upgrading from other UI libraries
|
|
|
|
## Examples
|
|
|
|
See the `examples/` directory for:
|
|
- Complete component implementations
|
|
- Form patterns with validation
|
|
- Dashboard layouts
|
|
- Authentication flows
|
|
- Data table implementations
|