Shadcn

shadcn/ui Development Guidelines

Best practices for using shadcn/ui components with Tailwind CSS and Radix UI primitives.

Core Principles

1. Copy, Don't Install: Components are copied to your project, not installed as dependencies
2. Customizable: Modify components directly in your codebase
3. Accessible: Built on Radix UI primitives with ARIA support
4. Type-Safe: Full TypeScript support
5. Composable: Build complex UIs from simple primitives

Installation

Initial Setup

npx shadcn@latest init

Add Components

# Add individual components
npx shadcn@latest add button
npx shadcn@latest add form
npx shadcn@latest add dialog

# Add multiple
npx shadcn@latest add button card dialog

Troubleshooting

npm Cache Errors (ENOTEMPTY)

If npx shadcn@latest add fails with npm cache errors like ENOTEMPTY or syscall rename:

Solution 1: Clear npm cache

npm cache clean --force
npx shadcn@latest add table

Solution 2: Use pnpm (recommended)

pnpm dlx shadcn@latest add table

Solution 3: Use yarn

yarn dlx shadcn@latest add table

Solution 4: Manual component installation

Visit the shadcn/ui documentation for the specific component and copy the code directly into your project.

Component Usage

Button & Card

import { Button } from '@/components/ui/button';
import { Card, CardHeader, CardTitle, CardDescription, CardContent } from '@/components/ui/card';

// Variants
Default
Destructive
Outline

// Card

  
    {post.title}
    {post.author}
  
  
    {post.excerpt}
  

Dialog

import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, DialogTrigger } from '@/components/ui/dialog';
import { Button } from '@/components/ui/button';

export function CreatePostDialog() {
  return (
    
      
        Create Post
      
      
        
          Create New Post
          
            Fill in the details below to create a new post.
          
        
        
      
    
  );
}

Forms

Basic Form with react-hook-form

'use client';

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import * as z from 'zod';
import { Button } from '@/components/ui/button';
import { Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage } from '@/components/ui/form';
import { Input } from '@/components/ui/input';
import { Textarea } from '@/components/ui/textarea';

const formSchema = z.object({
  title: z.string().min(1, 'Title is required'),
  content: z.string().min(10, 'Content must be at least 10 characters')
});

export function PostForm() {
  const form = useForm>({
    resolver: zodResolver(formSchema),
    defaultValues: {
      title: '',
      content: ''
    }
  });

  const onSubmit = (values: z.infer) => {
    console.log(values);
  };

  return (
    
      
         (
            
              Title
              
                
              
              
            
          )}
        />

         (
            
              Content
              
                
              
              
            
          )}
        />

        Create Post
      
    
  );
}

Select Field

 (
    
      Category
      
        
          
            
          
        
        
          Technology
          Design
          Business
        
      
      
    
  )}
/>

Data Display

Table

import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/components/ui/table';

export function PostsTable({ posts }: { posts: Post[] }) {
  return (
    
      
        
          Title
          Author
          Status
          Actions
        
      
      
        {posts.map((post) => (
          
            {post.title}
            {post.author.name}
            
              
                {post.published ? 'Published' : 'Draft'}
              
            
            
              Edit
            
          
        ))}
      
    
  );
}

Navigation

Badge & Dropdown Menu

import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger } from '@/components/ui/dropdown-menu';
import { Button } from '@/components/ui/button';

export function UserMenu() {
  return (
    
      
        
          
        
      
      
        My Account
        
        Profile
        Settings
        
        Log out
      
    
  );
}

Tabs

import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';

export function PostTabs() {
  return (
    
      
        Published
        Drafts
        Archived
      
      
        
      
      
        
      
      
        
      
    
  );
}

Feedback

Toast

'use client';

import { useToast } from '@/components/ui/use-toast';
import { Button } from '@/components/ui/button';

export function ToastExample() {
  const { toast } = useToast();

  return (
     {
        toast({
          title: 'Post created',
          description: 'Your post has been published successfully.'
        });
      }}
    >
      Create Post
    
  );
}

// With variant
toast({
  variant: 'destructive',
  title: 'Error',
  description: 'Failed to create post. Please try again.'
});

Alert

import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
import { AlertCircle } from 'lucide-react';

export function AlertExample() {
  return (
    
      
      Error
      
        Your session has expired. Please log in again.
      
    
  );
}

Loading States

Skeleton

import { Skeleton } from '@/components/ui/skeleton';

export function PostCardSkeleton() {
  return (
    
      
      
        
        
      
    
  );
}

Customization

Modifying Components

Components are in your codebase - edit them directly:

// components/ui/button.tsx
export const buttonVariants = cva(
  "inline-flex items-center justify-center...",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        // Add custom variant
        brand: "bg-gradient-to-r from-blue-500 to-purple-600 text-white"
      }
    }
  }
);

Using Custom Variant

Custom Brand Button

Theming

CSS Variables (OKLCH Format)

shadcn/ui now uses OKLCH color format for better color accuracy and perceptual uniformity:

/* app/globals.css */
@layer base {
  :root {
    --background: oklch(1 0 0);
    --foreground: oklch(0.145 0 0);
    --primary: oklch(0.205 0 0);
    --primary-foreground: oklch(0.985 0 0);
    /* ... */
  }

  .dark {
    --background: oklch(0.145 0 0);
    --foreground: oklch(0.985 0 0);
    --primary: oklch(0.598 0.15 264);
    --primary-foreground: oklch(0.205 0 0);
    /* ... */
  }
}

Dark Mode

// components/theme-toggle.tsx
'use client';

import { Moon, Sun } from 'lucide-react';
import { useTheme } from 'next-themes';
import { Button } from '@/components/ui/button';

export function ThemeToggle() {
  const { setTheme, theme } = useTheme();

  return (
     setTheme(theme === 'light' ? 'dark' : 'light')}
    >
      
      
      Toggle theme
    
  );
}

Composition Patterns

Combining Components

export function CreatePostCard() {
  return (
    
      
        Create Post
        Share your thoughts with the world
      
      
        
      
      
        Save Draft
        Publish
      
    
  );
}

Modal with Form

export function CreatePostModal() {
  const [open, setOpen] = useState(false);

  return (
    
      
        New Post
      
      
        
          Create Post
        
         setOpen(false)} />
      
    
  );
}

Additional Resources

For detailed information, see:

• [Component Catalog](resources/component-catalog.md)
• [Form Patterns](resources/form-patterns.md)
• [Theming Guide](resources/theming.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: blencorp
• Source: blencorp/claude-code-kit
• License: MIT

Install and usage instructions live in the source repository linked above.