shadcn-ui-patterns

ShadCN UI Patterns - November 2025 Standards

When to Use

• Building new UI components
• Refactoring existing components to use ShadCN
• Implementing forms with validation
• Creating modals, dialogs, and overlays
• Ensuring accessibility compliance

Why ShadCN UI?

• Copy-paste, not npm - Full ownership of component code
• Radix UI primitives - Accessibility built-in (WCAG 2.1 AA compliant)
• TailwindCSS-first - Full customization, no CSS-in-JS
• TypeScript-native - Type-safe props and variants
• Server Component compatible - Works with Next.js 15 App Router

Core Principles

1. Component Installation Pattern

# Install individual components as needed
npx shadcn@latest add button
npx shadcn@latest add dialog
npx shadcn@latest add form
npx shadcn@latest add input
npx shadcn@latest add label

Components are copied to src/components/ui/ directory - you own the code.

2. Component Usage Patterns

Button Component

import { Button } from "@/components/ui/button"

// ✅ DO: Use semantic variants
<Button variant="default">Save</Button>
<Button variant="destructive">Delete</Button>
<Button variant="outline">Cancel</Button>
<Button variant="ghost">Skip</Button>
<Button variant="link">Learn More</Button>

// ✅ DO: Use size variants
<Button size="default">Medium</Button>
<Button size="sm">Small</Button>
<Button size="lg">Large</Button>
<Button size="icon"><Icon /></Button>

// ❌ DON'T: Create custom buttons without using Button component
<button className="px-4 py-2 bg-blue-500">Bad</button>

Dialog/Modal Component

import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"

// ✅ DO: Use proper dialog structure (accessibility)
<Dialog>
  <DialogTrigger asChild>
    <Button>Open Settings</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Settings</DialogTitle>
      <DialogDescription>
        Configure your application settings here.
      </DialogDescription>
    </DialogHeader>
    {/* Dialog content */}
  </DialogContent>
</Dialog>

// ❌ DON'T: Skip DialogHeader or DialogTitle (breaks screen readers)
<DialogContent>
  <h2>Settings</h2> {/* Wrong - use DialogTitle */}
</DialogContent>