shadcn/ui 컴포넌트 라이브러리 완벽 가이드

shadcn/ui는 Tailwind CSS와 Radix UI를 기반으로 한 재사용 가능한 컴포넌트 라이브러리입니다. 복사하여 붙여넣는 방식으로 작동하며, 완전히 커스터마이징 가능한 UI 컴포넌트를 제공합니다.

---

---

들어가며

이 글에서는 shadcn/ui 컴포넌트 라이브러리 완벽 가이드에 대해 상세히 알아보겠습니다. 총 12가지 주요 개념을 다루며, 각각의 개념에 대한 설명과 실제 코드 예제를 함께 제공합니다.

목차

1. shadcn/ui_설치_및_초기화
2. Button_컴포넌트_추가
3. Button_Variants_사용하기
4. Card_컴포넌트_구조
5. Input_컴포넌트_사용
6. Dialog_컴포넌트_활용
7. Form_컴포넌트와_react-hook-form_통합
8. Select_컴포넌트_사용
9. Toast_알림_표시
10. Theme_커스터마이징
11. Accordion_컴포넌트_구현
12. Badge_컴포넌트로_태그_표시

---

1. shadcn/ui 설치 및 초기화

개요

shadcn/ui를 프로젝트에 설치하고 초기 설정을 진행합니다. CLI를 통해 간단하게 초기화할 수 있습니다.

코드 예제

npx shadcn-ui@latest init

# 설정 옵션 선택
# - TypeScript 사용 여부
# - 스타일 (New York / Default)
# - 색상 테마 선택

설명

init 명령어로 shadcn/ui를 설정하면 components.json 파일이 생성되고, 필요한 의존성이 자동으로 설치됩니다.

---

2. Button 컴포넌트 추가

개요

shadcn/ui의 Button 컴포넌트를 프로젝트에 추가합니다. 컴포넌트는 소스 코드로 추가되어 자유롭게 수정 가능합니다.

코드 예제

npx shadcn-ui@latest add button

// 사용 예시
import { Button } from "@/components/ui/button"

export default function App() {
  return <Button>클릭하세요</Button>
}

설명

add 명령어로 컴포넌트를 추가하면 components/ui 폴더에 소스 코드가 복사되어, npm 패키지가 아닌 직접 수정 가능한 코드로 관리됩니다.

---

3. Button Variants 사용하기

개요

Button 컴포넌트는 다양한 variant를 제공하여 여러 스타일을 쉽게 적용할 수 있습니다.

코드 예제

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

export default function ButtonDemo() {
  return (
    <div className="flex gap-2">
      <Button variant="default">기본</Button>
      <Button variant="destructive">삭제</Button>
      <Button variant="outline">외곽선</Button>
      <Button variant="ghost">고스트</Button>
    </div>
  )
}

설명

variant prop을 통해 버튼의 스타일을 변경할 수 있으며, class-variance-authority 라이브러리로 구현되어 있습니다.

---

4. Card 컴포넌트 구조

개요

Card 컴포넌트는 Header, Title, Description, Content, Footer로 구성된 레이아웃 컴포넌트입니다.

코드 예제

import {
  Card, CardHeader, CardTitle,
  CardDescription, CardContent
} from "@/components/ui/card"

export default function CardDemo() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>제목</CardTitle>
        <CardDescription>설명 텍스트</CardDescription>
      </CardHeader>
      <CardContent>카드 내용</CardContent>
    </Card>
  )
}

설명

Card 컴포넌트는 의미 있는 하위 컴포넌트로 구성되어 있어 일관된 레이아웃을 쉽게 만들 수 있습니다.

---

5. Input 컴포넌트 사용

개요

Input 컴포넌트는 Tailwind CSS 스타일이 적용된 기본 입력 필드입니다.

코드 예제

import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export default function InputDemo() {
  return (
    <div className="space-y-2">
      <Label htmlFor="email">이메일</Label>
      <Input type="email" id="email" placeholder="이메일 입력" />
    </div>
  )
}

설명

Input 컴포넌트는 HTML input 엘리먼트를 확장하여 모든 기본 props를 지원하며, 일관된 디자인 시스템을 제공합니다.

---

6. Dialog 컴포넌트 활용

개요

Dialog는 Radix UI를 기반으로 한 접근성이 좋은 모달 컴포넌트입니다.

코드 예제

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

export default function DialogDemo() {
  return (
    <Dialog>
      <DialogTrigger>열기</DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>다이얼로그 제목</DialogTitle>
        </DialogHeader>
        <p>다이얼로그 내용입니다.</p>
      </DialogContent>
    </Dialog>
  )
}

설명

DialogTrigger로 열림을 제어하고, DialogContent 안에 내용을 배치하여 키보드 네비게이션과 스크린 리더를 지원하는 접근성 높은 모달을 만들 수 있습니다.

---

7. Form 컴포넌트와 react-hook-form 통합

개요

shadcn/ui의 Form 컴포넌트는 react-hook-form과 zod를 통합하여 강력한 폼 검증을 제공합니다.

코드 예제

import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import * as z from "zod"
import { Form, FormField, FormItem, FormLabel, FormControl } from "@/components/ui/form"
import { Input } from "@/components/ui/input"

const formSchema = z.object({
  username: z.string().min(2, "2글자 이상 입력하세요")
})

export default function FormDemo() {
  const form = useForm<z.infer<typeof formSchema>>({
    resolver: zodResolver(formSchema)
  })

  return (
    <Form {...form}>
      <FormField name="username" render={({ field }) => (
        <FormItem>
          <FormLabel>사용자명</FormLabel>
          <FormControl><Input {...field} /></FormControl>
        </FormItem>
      )} />
    </Form>
  )
}

설명

zod 스키마로 검증 규칙을 정의하고, react-hook-form으로 폼 상태를 관리하여 타입 안전한 폼을 쉽게 구현할 수 있습니다.

---

8. Select 컴포넌트 사용

개요

Select 컴포넌트는 접근성이 좋은 드롭다운 선택 메뉴를 제공합니다.

코드 예제

import {
  Select, SelectContent, SelectItem,
  SelectTrigger, SelectValue
} from "@/components/ui/select"

export default function SelectDemo() {
  return (
    <Select>
      <SelectTrigger className="w-[180px]">
        <SelectValue placeholder="선택하세요" />
      </SelectTrigger>
      <SelectContent>
        <SelectItem value="react">React</SelectItem>
        <SelectItem value="vue">Vue</SelectItem>
        <SelectItem value="angular">Angular</SelectItem>
      </SelectContent>
    </Select>
  )
}

설명

SelectTrigger로 선택 버튼을 만들고, SelectContent 안에 SelectItem으로 옵션을 추가하여 키보드로도 조작 가능한 선택 메뉴를 만듭니다.

---

9. Toast 알림 표시

개요

Toast 컴포넌트는 사용자에게 일시적인 알림 메시지를 표시합니다.

코드 예제

import { useToast } from "@/components/ui/use-toast"
import { Button } from "@/components/ui/button"

export default function ToastDemo() {
  const { toast } = useToast()

  return (
    <Button onClick={() => {
      toast({
        title: "알림",
        description: "작업이 완료되었습니다."
      })
    }}>
      토스트 표시
    </Button>
  )
}

설명

useToast 훅을 사용하여 toast 함수를 호출하면 화면 하단에 알림이 표시되며, 자동으로 사라집니다.

---

10. Theme 커스터마이징

개요

shadcn/ui는 CSS 변수를 통해 전체 테마를 쉽게 커스터마이징할 수 있습니다.

코드 예제

/* globals.css */
@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 221.2 83.2% 53.3%;
    --primary-foreground: 210 40% 98%;
    --radius: 0.5rem;
  }
}

/* 컴포넌트에서 자동으로 적용됨 */

설명

CSS 변수를 수정하면 모든 shadcn/ui 컴포넌트의 색상과 스타일이 자동으로 변경되어 일관된 디자인 시스템을 유지할 수 있습니다.

---

11. Accordion 컴포넌트 구현

개요

Accordion은 펼치고 접을 수 있는 콘텐츠 섹션을 만드는 컴포넌트입니다.

코드 예제

import {
  Accordion, AccordionContent,
  AccordionItem, AccordionTrigger
} from "@/components/ui/accordion"

export default function AccordionDemo() {
  return (
    <Accordion type="single" collapsible>
      <AccordionItem value="item-1">
        <AccordionTrigger>질문 1</AccordionTrigger>
        <AccordionContent>답변 내용입니다.</AccordionContent>
      </AccordionItem>
      <AccordionItem value="item-2">
        <AccordionTrigger>질문 2</AccordionTrigger>
        <AccordionContent>또 다른 답변입니다.</AccordionContent>
      </AccordionItem>
    </Accordion>
  )
}

설명

type="single"은 한 번에 하나만 열리도록 하고, collapsible 속성은 열린 항목을 다시 클릭해 닫을 수 있게 합니다.

---

12. Badge 컴포넌트로 태그 표시

개요

Badge는 상태나 카테고리를 표시하는 작은 라벨 컴포넌트입니다.

코드 예제

import { Badge } from "@/components/ui/badge"

export default function BadgeDemo() {
  return (
    <div className="flex gap-2">
      <Badge>기본</Badge>
      <Badge variant="secondary">보조</Badge>
      <Badge variant="destructive">경고</Badge>
      <Badge variant="outline">외곽선</Badge>
    </div>
  )
}

설명

Badge 컴포넌트는 다양한 variant를 제공하여 상태나 카테고리를 시각적으로 구분할 수 있으며, 간결한 정보 표시에 적합합니다.

---

마치며

이번 글에서는 shadcn/ui 컴포넌트 라이브러리 완벽 가이드에 대해 알아보았습니다. 총 12가지 개념을 다루었으며, 각각의 사용법과 예제를 살펴보았습니다.

관련 태그

#React #shadcn/ui #TailwindCSS #RadixUI #UIComponents