shadcn/ui Components

Full Reference: See advanced.md for accessibility patterns, virtualized tables, form integration with react-hook-form, testing patterns, and dark mode setup.

When NOT to Use This Skill

• Radix UI primitives only - Use radix-ui skill for unstyled components
• Custom component library - Build from scratch with Radix + Tailwind
• Different UI framework - Material-UI, Chakra, Ant Design have own patterns
• No Tailwind project - shadcn/ui requires Tailwind CSS

Installation

# Initialize shadcn/ui in your project
npx shadcn@latest init

# Add components
npx shadcn@latest add button card dialog dropdown-menu form input table

Button Variants

import { Button } from '@/components/ui/button';

<Button variant="default">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="destructive">Delete</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>

// With icon
<Button>
  <PlusIcon className="mr-2 h-4 w-4" />
  Add Item
</Button>

// Loading state
<Button disabled={isLoading}>
  {isLoading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
  Save
</Button>

Card Layout

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

<Card>
  <CardHeader>
    <CardTitle>User Profile</CardTitle>
  </CardHeader>
  <CardContent>
    {/* Content */}
  </CardContent>
</Card>

Dialog (Modal)

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

<Dialog open={open} onOpenChange={setOpen}>
  <DialogTrigger asChild>
    <Button>Create User</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Create User</DialogTitle>
    </DialogHeader>
    <UserForm onSuccess={() => setOpen(false)} />
  </DialogContent>
</Dialog>

Data Table

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

<Table>
  <TableHeader>
    <TableRow>
      <TableHead>Name</TableHead>
      <TableHead>Email</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    {users.map((user) => (
      <TableRow key={user.id}>
        <TableCell>{user.name}</TableCell>
        <TableCell>{user.email}</TableCell>
      </TableRow>
    ))}
  </TableBody>
</Table>

Utils (cn function)

// lib/utils.ts
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

// Usage
<div className={cn("base-class", isActive && "active-class")} />

Anti-Patterns

Quick Troubleshooting

Theme Configuration

/* index.css */
@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 222.2 47.4% 11.2%;
    /* ... more variables */
  }
  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
  }
}

Monitoring Metrics

Checklist

• Accessible labels on all form fields
• DialogTitle and DialogDescription present
• aria-describedby for error messages
• Loading states with aria-busy
• Lazy loading for heavy components
• Virtual scrolling for large lists
• Form validation with Zod
• Dark mode with next-themes
• Component tests with Testing Library
• Accessibility tests with jest-axe

Reference Documentation

• Component Reference
• Theming