shadcn/ui

Quick Verdict

When to use it: Any React/Next.js project that needs UI components. The copy-paste model is a feature, not a limitation.

When not to: You need specialized widgets (data grids, complex date pickers, rich text editors) — shadcn covers fundamentals, not everything.

Best For

• Next.js App Router — most components work as server components out of the box
• AI-assisted development — consistent patterns, well-documented, heavily indexed in LLM training data
• Teams that want code ownership — modify any component without fighting upstream abstractions
• Dark mode / theming — CSS custom properties + Tailwind tokens make theming straightforward

Avoid If

• You need a comprehensive widget library beyond the fundamentals
• Your team refuses to use Tailwind — the components are Tailwind-native
• You need strict Material Design or Ant Design compliance

Why the Copy-Paste Model Wins

Traditional component libraries create dependency lock-in. You can't change component internals without forking, you wait for upstream PRs, and major version upgrades can break your UI.

shadcn flipped this: npx shadcn add button copies the button component into your src/components/ui/ directory. You own it. You modify it. You break it if you want. No upstream dependency, no version constraint.

The v4 release moved from Radix to Base UI primitives and introduced cleaner styling. The CLI remains the same — one command per component.

Hidden Costs

Zero. No subscription, no licensing, no npm package to pay for. The only cost is reading and understanding the components you modify — which you should do anyway since you own them.

Correct vs Cargo-Culted Patterns

Wrong — importing like a package:

// ❌ This doesn't exist
import { Button } from 'shadcn-ui'

Right — from your own components directory:

// ✅ You own this file after running npx shadcn add button
import { Button } from '@/components/ui/button'

Wrong — hardcoded variants instead of cn():

// ❌ Class conflicts, hard to maintain
<button className={`px-4 py-2 ${variant === 'outline' ? 'border border-input' : 'bg-primary'}`}>

Right — cn() for conditional variants:

// ✅ tailwind-merge resolves conflicts, readable
<button className={cn(
  'px-4 py-2 rounded-md',
  variant === 'outline' && 'border border-input bg-transparent',
  variant === 'default' && 'bg-primary text-primary-foreground',
)}>

Wrong — ignoring theme config:

// ❌ Hardcoded color defeats the theming system
<div className="bg-[#1a1a2e] text-[#ffffff]">

Right — CSS custom properties via theme:

/* globals.css — define once, use everywhere */
@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
  }
}

AI Coding Notes

Always specify your shadcn version (v3 Radix vs v4 Base UI — different component internals). Tell the AI:

• "Using shadcn/ui v4 with Base UI"
• "Use cn() from @/lib/utils for conditional classes"
• "Components are in src/components/ui/"

Provide the component file as context when asking for modifications — AI produces better changes when it can see the actual source.

Common AI Mistakes

1. Importing from npm package — shadcn is not a dependency. Components are in your src/components/ui/ directory.
2. v3 patterns in v4 project — v4 uses Base UI instead of Radix, @theme inline instead of tailwind.config.ts
3. Fighting Tailwind — shadcn and Tailwind are inseparable. If you need CSS Modules, use a different library.
4. Not customizing via CSS variables — hardcoding colors instead of using the theme token system.
5. Using v4 CLI to add v3 components — always run npx shadcn add with the correct version.

Start With / Grow Into / Avoid Until Needed

Start with shadcn for any React/Next.js project that needs UI components. The CLI makes it fast.

Grow into the theme system once your design tokens are defined — CSS custom properties + @theme create a maintainable design system.

Avoid until needed: Custom component wrapping layers, design system packages on top of shadcn — start lean.

Migration Implications

Low pain. You own the component files — they're just TypeScript + Tailwind. Migrating to a different component library means rewriting UI, not a library upgrade.