shadcn-ui

$2a

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

• Use get_component to retrieve the source code

• Create the file in components/ui/[component-name].tsx

• Install peer dependencies manually

• 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 &#x26;&#x26; <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.):

• List available blocks: Use list_blocks with optional category filter

• Get block source: Use get_block with the block name

• 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

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

import {

  Dialog,

  DialogContent,

  DialogDescription,

  DialogHeader,

  DialogTitle,

  DialogTrigger,

} from "@/components/ui/dialog"

Data Display

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:

{

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

• Type check: Run tsc --noEmit to verify TypeScript

• Lint: Run your linter to catch style issues

• Test accessibility: Use tools like axe DevTools

• Visual QA: Test in light and dark modes

• 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