/shadcn

name: shadcn
description: shadcn/ui expert guidance — CLI, component installation, composition patterns, custom registries, theming, Tailwind CSS integration, and high-quality interface design. Use when initializing shadcn, adding components, composing product UI, building custom registries, configuring themes, or troubleshooting component issues.
metadata:
  priority: 6
  docs:
    - "https://ui.shadcn.com/docs"
    - "https://ui.shadcn.com/docs/components"
  pathPatterns:
    - 'components.json'
    - 'components/ui/**'
    - 'src/components/ui/**'
    - 'apps/*/components/ui/**'
    - 'apps/*/src/components/ui/**'
    - 'packages/*/components/ui/**'
    - 'packages/*/src/components/ui/**'
  bashPatterns:
    - '\bnpx\s+shadcn\b'
    - '\bnpx\s+shadcn@latest\s+(init|add|build|search|list|migrate|info|docs|view)\b'
    - '\bnpx\s+create-next-app\b'
    - '\bbunx\s+create-next-app\b'
    - '\bpnpm\s+create\s+next-app\b'
    - '\bnpm\s+create\s+next-app\b'
validate:
  -
    pattern: '"base"\s*:\s*"base-ui"'
    message: 'AI Elements components use Radix-specific APIs (asChild, openDelay) and have type errors with Base UI. If this project uses AI Elements, reinitialize with: npx shadcn@latest init -d --base radix -f'
    severity: warn
retrieval:
  aliases:
    - shadcn ui
    - component library
    - ui components
    - tailwind components
  intents:
    - add shadcn component
    - set up shadcn
    - customize theme
    - build ui
  entities:
    - shadcn/ui
    - Tailwind CSS
    - registry
    - theme
    - components.json

shadcn/ui

You are an expert in shadcn/ui — a collection of beautifully designed, accessible, and customizable React components built on Radix UI primitives and Tailwind CSS. Components are added directly to your codebase as source code, not installed as a dependency.

Key Concept

shadcn/ui is **not a component library** in the traditional sense. You don't install it as a package. Instead, the CLI copies component source code into your project, giving you full ownership and customization ability.

CLI Commands

Initialize (non-interactive — ALWAYS use this)

**IMPORTANT**: `shadcn init` is interactive by default. Always use `-d` (defaults) for non-interactive initialization:

# Non-interactive init with defaults — USE THIS
npx shadcn@latest init -d

# Non-interactive with a preset (recommended for consistent design systems)
npx shadcn@latest init --preset <code> -f

# Non-interactive with explicit base library choice
npx shadcn@latest init -d --base radix
npx shadcn@latest init -d --base base-ui

# Scaffold a full project template (CLI v4)

> **AI Elements compatibility**: Always use `--base radix` (the default) when the project uses or may use AI Elements. AI Elements components rely on Radix APIs and have type errors with Base UI.

npx shadcn@latest init --template next -d
npx shadcn@latest init --template vite -d

Options:

• `-d, --defaults` — **Use default configuration, skip all interactive prompts** (REQUIRED for CI/agent use)
• `-y, --yes` — Skip confirmation prompts (does NOT skip library selection — use `-d` instead)
• `-f, --force` — Force overwrite existing configuration
• `-t, --template` — Scaffold full project template (`next`, `vite`, `react-router`, `astro`, `laravel`, `tanstack-start`)
• `--preset` — Apply a design system preset (colors, theme, icons, fonts, radius) as a single shareable code
• `--base` — Choose primitive library: `radix` (default) or `base-ui`
• `--monorepo` — Set up a monorepo structure

> **WARNING**: `-y`/`--yes` alone does NOT make init fully non-interactive — it still prompts for component library selection. Always use `-d` to skip ALL prompts.

> **Deprecated in CLI v4**: `--style`, `--base-color`, `--src-dir`, `--no-base-style`, and `--css-variables` flags are removed and will error. The `registry:build` and `registry:mcp` registry types are also deprecated. Use `registry:base` and `registry:font` instead.

The init command: 1. Detects your framework (Next.js, Vite, React Router, Astro, Laravel, TanStack Start) 2. Installs required dependencies (Radix UI, tailwind-merge, class-variance-authority) 3. Creates `components.json` configuration 4. Sets up the `cn()` utility function 5. Configures CSS variables for theming

Add Components

# Add specific components
npx shadcn@latest add button dialog card

# Add all available components
npx shadcn@latest add --all

# Add from a custom registry
npx shadcn@latest add @v0/dashboard
npx shadcn@latest add @acme/custom-button

# Add from AI Elements registry
npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/all.json

Options:

• `-o, --overwrite` — Overwrite existing files
• `-p, --path` — Custom install path
• `-a, --all` — Install all components
• `--dry-run` — Preview what will be added without writing files
• `--diff` — Show diff of changes when updating existing components
• `--view` — Display a registry item's source code inline

Search & List

npx shadcn@latest search button
npx shadcn@latest list @v0

Build (Custom Registry)

npx shadcn@latest build
npx shadcn@latest build ./registry.json -o ./public/r

View, Info & Docs (CLI v4)

# View a registry item's source before installing
npx shadcn@latest view button

# Show project diagnostics — config, installed components, dependencies
npx shadcn@latest info

# Get docs, code, and examples for any component (agent-friendly output)
npx shadcn@latest docs button
npx shadcn@latest docs dialog

> **`shadcn docs`** gives coding agents the context to use primitives correctly — returns code examples, API reference, and usage patterns inline.

Migrate

npx shadcn@latest migrate rtl    # RTL support migration
npx shadcn@latest migrate radix  # Migrate to unified radix-ui package
npx shadcn@latest migrate icons  # Icon library changes

# Migrate components outside the default ui directory
npx shadcn@latest migr