/shadcn-ui

name: shadcn-ui
description: |
  Complete shadcn/ui component library guide including installation, configuration, and implementation of accessible React components. Use when setting up shadcn/ui, installing components, building forms with React Hook Form and Zod, customizing themes with Tailwind CSS, or implementing UI patterns like buttons, dialogs, dropdowns, tables, and complex form layouts.
  안티-트리거: "Material UI", "Chakra UI", "순수 CSS 컴포넌트"
user-invocable: false
language: typescript,tsx
framework: react,nextjs,tailwindcss
license: MIT
allowed-tools: Read, Write, Bash, Edit, Glob

shadcn/ui Component Patterns

Expert guide for building accessible, customizable UI components with shadcn/ui, Radix UI, and Tailwind CSS.

> 스니펫 조회: 기본은 official-ui-reference.md(공식 문서 최신 덤프, blocks·chart 등 범위 넓음)를 읽고, 거기 없는 스니펫만 ui-reference.md(구버전 발췌)에서 보조 조회한다.

Table of Contents

• [When to Use](#when-to-use)
• [Quick Start](#quick-start)
• [Installation & Setup](#installation--setup)
• [Project Configuration](#project-configuration)
• [Core Components](#core-components)
• [Button](#button-component)
• [Input & Form Fields](#input--form-fields)
• [Forms with Validation](#forms-with-validation)
• [Card](#card-component)
• [Dialog (Modal)](#dialog-modal-component)
• [Select (Dropdown)](#select-dropdown-component)
• [Sheet (Slide-over)](#sheet-slide-over-component)
• [Menubar & Navigation](#menubar--navigation)
• [Table](#table-component)
• [Toast Notifications](#toast-notifications)
• [Advanced Patterns](#advanced-patterns)
• [Customization](#customization)
• [Next.js Integration](#nextjs-integration)
• [Best Practices](#best-practices)
• [Common Component Combinations](#common-component-combinations)

When to Use

• Setting up a new project with shadcn/ui
• Installing or configuring individual components
• Building forms with React Hook Form and Zod validation
• Creating accessible UI components (buttons, dialogs, dropdowns, sheets)
• Customizing component styling with Tailwind CSS
• Implementing design systems with shadcn/ui
• Building Next.js applications with TypeScript
• Creating complex layouts and data displays

Quick Start

For new projects, use the automated setup:

# Create Next.js project with shadcn/ui
npx create-next-app@latest my-app --typescript --tailwind --eslint --app
cd my-app
npx shadcn@latest init

# Install essential components
npx shadcn@latest add button input form card dialog select

For existing projects:

# Install dependencies
npm install tailwindcss-animate class-variance-authority clsx tailwind-merge lucide-react

# Initialize shadcn/ui
npx shadcn@latest init

What is shadcn/ui?

shadcn/ui is **not** a traditional component library or npm package. Instead:

• It's a **collection of reusable components** that you can copy into your project
• Components are **yours to customize** - you own the code
• Built with **Radix UI** primitives for accessibility
• Styled with **Tailwind CSS** utilities
• Includes CLI tool for easy component installation

Installation & Setup

Initial Setup

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

During setup, you'll configure:

• TypeScript or JavaScript
• Style (Default, New York, etc.)
• Base color theme
• CSS variables or Tailwind CSS classes
• Component installation path

Installing Individual Components

# Install a single component
npx shadcn@latest add button

# Install multiple components
npx shadcn@latest add button input form

# Install all components
npx shadcn@latest add --all

Manual Installation

If you prefer manual setup:

# Install dependencies for a specific component
npm install @radix-ui/react-slot

# Copy component code from ui.shadcn.com
# Place in src/components/ui/

Project Configuration

Required Dependencies

{
  "dependencies": {
    "@radix-ui/react-accordion": "^1.1.2",
    "@radix-ui/react-alert-dialog": "^1.0.5",
    "@radix-ui/react-dialog": "^1.0.5",
    "@radix-ui/react-dropdown-menu": "^2.0.6",
    "@radix-ui/react-label": "^2.0.2",
    "@radix-ui/react-select": "^2.0.0",
    "@radix-ui/react-separator": "^1.0.3",
    "@radix-ui/react-slot": "^1.0.2",
    "@radix-ui/react-toast": "^1.1.5",
    "class-variance-authority": "^0.7.0",
    "clsx": "^2.0.0",
    "lucide-react": "^0.294.0",
    "tailwind-merge": "^2.0.0",
    "tailwindcss-animate": "^1.0.7"
  }
}

TSConfig Configuration

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "es6"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "baseUrl": ".",
    "paths": {
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

Tailwind Configuration

// tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: ["class"],
  content: [
    './pages/**/*.{ts,tsx}',
    './components/**/*.{ts,tsx}',
    './app/**/*.{ts,tsx}',
    './src/**/*.{ts,tsx}',
  ],
  prefix: "",
  theme: {
    container: {
      center: true,
      padding: "2rem",
      screens: {
        "2xl": "1400px",
      },
    },
    extend: {
      colors: {
        border: "hsl(var(--border))",
        input: "hsl(var(--input))",
        ring: "hsl(var(--ring))",
        background: "hsl(var(--background))",
        foreground: "hsl(var(--foreground))",
        primary: {
          DEFAULT: "hsl(var(--primary))",
          foreground: "hsl(var(--primary-foreground))",
        },