shadcn/ui란 무엇인가요? 완벽 튜토리얼 (2026)

shadcn/ui란 무엇인가요? 2026년 완성 가이드

shadcn/ui는 전통적인 컴포넌트 라이브러리가 아닙니다. 이는 사용자가 프로젝트에 직접 복사하여 사용할 수 있는, 아름답게 디자인되고 재사용 가능한 컴포넌트들의 모음입니다. npm 패키지를 설치하고 내부를 알 수 없는 컴포넌트를 import하는 대신, 실제 소스 코드를 코드베이스에 직접 포함시켜 스타일링, 동작 및 접근성에 대한 완전한 제어권을 가질 수 있습니다.

Radix UI 프리미티브를 기반으로 구축되고 Tailwind CSS로 스타일링된 shadcn/ui는 React 생태계에서 가장 인기 있는 프론트엔드 도구 중 하나가 되었습니다. 이 튜토리얼에서는 초기 설정부터 고급 커스터마이징까지 모든 것을 다룹니다.

왜 shadcn/ui인가요?

shadcn/ui와 기존 컴포넌트 라이브러리의 비교는 다음과 같습니다:

기능	shadcn/ui	Material UI	Chakra UI	Ant Design
설치 방식	프로젝트에 직접 복사	npm 패키지	npm 패키지	npm 패키지
코드 소유권	직접 소유 (Yes)	소유 불가 (No)	소유 불가 (No)	소유 불가 (No)
스타일링	Tailwind CSS	Emotion/styled	Emotion	Less/CSS-in-JS
번들 크기	사용하는 코드만 포함	큼 (Large)	중간 (Medium)	큼 (Large)
커스터마이징	완전 자유 (소스 수정)	테마 오버라이드	테마 오버라이드	테마 오버라이드
접근성	Radix UI (매우 우수)	양호	양호	양호
TypeScript	완벽 지원	완벽 지원	완벽 지원	완벽 지원
프레임워크	React / Next.js	React	React	React

핵심 장점: 테마 오버라이드가 허용하는 범위를 넘어 컴포넌트의 동작이나 스타일을 수정해야 할 때, 라이브러리의 추상화와 싸우는 대신 실제 컴포넌트 코드를 직접 편집하면 됩니다.

Step 1: 새로운 프로젝트 설정하기

shadcn/ui는 Next.js와 가장 잘 작동하지만, Vite, Remix, Astro 및 기타 React 프레임워크도 지원합니다.

Next.js 사용 시 (권장)

npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir
cd my-app

Vite 사용 시

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install
npm install -D tailwindcss @tailwindcss/vite

Step 2: shadcn/ui 초기화

CLI를 실행하여 프로젝트에 shadcn/ui를 설정합니다:

npx shadcn@latest init

CLI가 다음과 같은 몇 가지 질문을 할 것입니다:

Which style would you like to use? > New York
Which color would you like to use as base color? > Zinc
Do you want to use CSS variables for colors? > Yes

이 과정이 완료되면 다음이 생성됩니다:

• components.json 설정 파일
• cn() 유틸리티 함수가 포함된 lib/utils.ts 파일
• 업데이트된 Tailwind 및 글로벌 CSS 설정

생성된 components.json은 다음과 같은 모습입니다:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "src/app/globals.css",
    "baseColor": "zinc",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  }
}

Step 3: 컴포넌트 추가하기

필요할 때마다 컴포넌트를 개별적으로 추가하세요:

# button 컴포넌트 추가
npx shadcn@latest add button

# 여러 컴포넌트를 한 번에 추가
npx shadcn@latest add card dialog dropdown-menu input label

# 모든 컴포넌트 추가 (권장하지 않음 -- 필요한 것만 추가하세요)
npx shadcn@latest add --all

각 명령어는 컴포넌트 소스 코드를 src/components/ui/ 디렉토리에 복사합니다. 예를 들어, button을 추가하면 다음과 같은 파일이 생성됩니다:

// src/components/ui/button.tsx
import * as React from "react"
import { Slot } from "@radix-ui/react-slot"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "@/lib/utils"

const buttonVariants = cva(
  "inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
        lg: "h-11 rounded-md px-8",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

// ... 컴포넌트의 나머지 부분

Step 4: 앱에서 컴포넌트 사용하기

컴포넌트를 다른 React 컴포넌트처럼 import하여 사용하세요:

import { Button } from "@/components/ui/button"
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export default function LoginPage() {
  return (
    <div className="flex min-h-screen items-center justify-center">
      <Card className="w-[400px]">
        <CardHeader>
          <CardTitle>Sign In</CardTitle>
          <CardDescription>Enter your credentials to access your account.</CardDescription>
        </CardHeader>
        <CardContent>
          <form className="space-y-4">
            <div className="space-y-2">
              <Label htmlFor="email">Email</Label>
              <Input id="email" type="email" placeholder="you@example.com" />
            </div>
            <div className="space-y-2">
              <Label htmlFor="password">Password</Label>
              <Input id="password" type="password" />
            </div>
            <Button type="submit" className="w-full">
              Sign In
            </Button>
          </form>
        </CardContent>
      </Card>
    </div>
  )
}

Step 5: 테마 커스터마이징

shadcn/ui는 테마 적용을 위해 CSS 변수를 사용합니다. globals.css를 편집하여 색상을 변경할 수 있습니다:

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 240 10% 3.9%;
    --primary: 240 5.9% 10%;
    --primary-foreground: 0 0% 98%;
    --secondary: 240 4.8% 95.9%;
    --secondary-foreground: 240 5.9% 10%;
    --accent: 240 4.8% 95.9%;
    --accent-foreground: 240 5.9% 10%;
    --destructive: 0 84.2% 60.2%;
    --destructive-foreground: 0 0% 98%;
    --muted: 240 4.8% 95.9%;
    --muted-foreground: 240 3.8% 46.1%;
    --border: 240 5.9% 90%;
    --ring: 240 5.9% 10%;
    --radius: 0.5rem;
  }

  .dark {
    --background: 240 10% 3.9%;
    --foreground: 0 0% 98%;
    --primary: 0 0% 98%;
    --primary-foreground: 240 5.9% 10%;
    /* ... 다크 모드 값들 */
  }
}

shadcn/ui 웹사이트에는 시각적으로 색상을 선택하고 CSS 변수를 복사할 수 있는 테마 생성기(theme generator)가 있습니다.

Step 6: 복잡한 컴포넌트 구축하기

컴포넌트 코드를 직접 소유하고 있으므로 자유롭게 확장할 수 있습니다. 다음은 shadcn/ui를 사용하여 정렬, 필터링, 페이지네이션 기능이 포함된 데이터 테이블을 구축하는 예시입니다:

# 필요한 컴포넌트 추가
npx shadcn@latest add table badge select

import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@/components/ui/table"
import { Badge } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { useState } from "react"

interface User {
  id: number
  name: string
  email: string
  role: "admin" | "user" | "moderator"
  status: "active" | "inactive"
}

const users: User[] = [
  { id: 1, name: "Alice Johnson", email: "alice@example.com", role: "admin", status: "active" },
  { id: 2, name: "Bob Smith", email: "bob@example.com", role: "user", status: "active" },
  { id: 3, name: "Carol Davis", email: "carol@example.com", role: "moderator", status: "inactive" },
]

export function UserTable() {
  const [search, setSearch] = useState("")

  const filtered = users.filter(
    (user) =>
      user.name.toLowerCase().includes(search.toLowerCase()) ||
      user.email.toLowerCase().includes(search.toLowerCase())
  )

  return (
    <div className="space-y-4">
      <Input
        placeholder="Search users..."
        value={search}
        onChange={(e) => setSearch(e.target.value)}
        className="max-w-sm"
      />
      <Table>
        <TableHeader>
          <TableRow>
            <TableHead>Name</TableHead>
            <TableHead>Email</TableHead>
            <TableHead>Role</TableHead>
            <TableHead>Status</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {filtered.map((user) => (
            <TableRow key={user.id}>
              <TableCell className="font-medium">{user.name}</TableCell>
              <TableCell>{user.email}</TableCell>
              <TableCell>
                <Badge variant="outline">{user.role}</Badge>
              </TableCell>
              <TableCell>
                <Badge variant={user.status === "active" ? "default" : "secondary"}>
                  {user.status}
                </Badge>
              </TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </div>
  )
}

시작할 때 필수적인 컴포넌트

가장 흔히 사용되는 shadcn/ui 컴포넌트들입니다:

컴포넌트	용도	의존성
Button	액션 및 CTA	없음
Input	텍스트 입력	없음
Card	콘텐츠 컨테이너	없음
Dialog	모달 및 팝업	Radix Dialog
Dropdown Menu	컨텍스트 메뉴	Radix Dropdown
Table	데이터 표시	없음
Form	폼 처리	React Hook Form + Zod
Toast	알림	Sonner
Sheet	사이드 패널	Radix Dialog
Tabs	탭 인터페이스	Radix Tabs
Command	검색 / 커맨드 팔레트	cmdk

자주 묻는 질문 (FAQ)

shadcn/ui는 무료인가요? 네, MIT 라이선스 하에 완전히 무료이며 오픈 소스입니다.

shadcn/ui를 쓰면 번들 크기가 커지나요? 아니요. 사용하는 컴포넌트만 추가하고 그 코드가 소스 코드의 일부가 되기 때문에 Tree-shaking이 완벽하게 작동합니다. 번들에는 사용자가 import한 것만 포함됩니다.

Next.js가 없는 일반 React에서도 사용할 수 있나요? 네. shadcn/ui는 Vite, Remix, Astro 및 기타 React 프레임워크를 지원합니다. CLI가 각 환경에 맞는 설정을 처리합니다.

컴포넌트를 어떻게 업데이트하나요? npx shadcn@latest diff를 실행하여 로컬 컴포넌트와 최신 버전 간의 변경 사항을 확인하세요. 그 후 필요한 업데이트를 선택적으로 적용할 수 있습니다.

다른 CSS 프레임워크와 함께 사용할 수 있나요? shadcn/ui는 Tailwind CSS를 위해 설계되었습니다. 다른 CSS 프레임워크와 함께 사용하려면 상당한 수정이 필요합니다.

shadcn/ui는 접근성을 지원하나요? 네. 대부분의 대화형 컴포넌트는 매우 우수한 키보드 탐색, 스크린 리더 지원 및 WAI-ARIA 준수를 제공하는 Radix UI 프리미티브를 기반으로 구축되었습니다.

마치며

shadcn/ui는 컴포넌트 라이브러리에 대한 우리의 사고방식 변화를 나타냅니다. UI를 제어하는 외부 패키지에 의존하는 대신, 코드베이스에 직접 상주하는 잘 디자인되고 접근성이 뛰어난 컴포넌트를 얻게 됩니다. 이 접근 방식은 검증된 패턴의 이점을 누리면서도 커스터마이징에 대한 완전한 통제권을 제공합니다.

미디어 생성을 위해 AI 서비스에 연결되는 프론트엔드를 구축 중이라면, Hypereal AI를 무료로 체험해 보세요. 카드 등록 없이 35크레딧이 제공됩니다.. API는 모든 React 프론트엔드와 호환되며, shadcn/ui 컴포넌트와 함께라면 AI 생성 콘텐츠를 위한 세련된 UI를 쉽게 만들 수 있습니다.