/shadcn-ui

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)**

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):

npx shadcn@latest create

For **existing projects**, initialize configuration:

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:

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`:

@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:

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/`):

// 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