shadcn-svelte 가이드
shadcn-svelte는 TypeScript, Tailwind CSS, Bits UI 기반의 접근성 높은 Svelte/SvelteKit 컴포넌트 모음이다. CLI로 컴포넌트를 설치하고 소스를 직접 수정할 수 있다.
사용 원칙
이 스킬의 주 목적은 화면 구성 시 알맞은 컴포넌트를 선택하고 올바르게 사용하도록 돕는 것이다. 아래 컴포넌트 목록을 참고해 작업에 적합한 컴포넌트를 추천하고 코드를 작성한다.
컴포넌트를 실제로 추가해야 할 때는 아래 "컴포넌트 설치" 절차를 따른다.
컴포넌트 설치
1. shadcn-svelte 설정 확인
컴포넌트를 추가하기 전에 작업공간에 shadcn-svelte가 초기화되어 있는지 확인한다:
ls components.json
- 파일이 있으면 → 이미 설정 완료. 바로 컴포넌트 추가로 이동.
- 파일이 없으면 → 사용자에게 직접 초기화를 요청한다:
shadcn-svelte가 초기화되어 있지 않습니다. 터미널에서 아래 명령어를 원하는 설정으로 먼저 실행해 주세요:
npx shadcn-svelte@latest init권장 설정:
- Base color:
Slate- Global CSS:
src/routes/+layout.svelte- Import aliases:
$lib,$lib/components,$lib/utils,$lib/hooks,$lib/components/ui완료되면 다시 알려주세요.
초기화 완료 확인 후 컴포넌트 추가로 진행한다.
2. 컴포넌트 추가 방식 선택
사용자에게 설치 방식을 확인한다:
A. 필요한 컴포넌트만 설치 (권장)
npx shadcn-svelte@latest add button
npx shadcn-svelte@latest add dialog card
B. 전체 컴포넌트 일괄 설치
npx shadcn-svelte@latest add --all
# 확인 프롬프트 없이
npx shadcn-svelte@latest add --all --yes
# 기존 파일 덮어쓰기
npx shadcn-svelte@latest add --all --overwrite
주요 CLI 옵션
| 옵션 | 설명 |
|---|---|
-a, --all | 모든 컴포넌트 설치 |
-y, --yes | 확인 프롬프트 건너뜀 |
-o, --overwrite | 기존 파일 덮어쓰기 |
--no-deps | 패키지 의존성 설치 제외 |
컴포넌트 임포트
import { Button } from "$lib/components/ui/button/index.js";
import { Dialog } from "$lib/components/ui/dialog/index.js";
컴포넌트 목록
Form & Input (폼 & 입력)
- Button: 버튼
- Button Group: 관련 버튼을 묶는 그룹
- Calendar: 날짜 선택 캘린더
- Checkbox: 체크박스
- Combobox: 자동완성 입력 + 커맨드 팔레트
- Date Picker: 범위/프리셋 포함 날짜 선택기
- Field: 레이블 + 컨트롤 + 도움말 조합 폼 필드
- Formsnap: Formsnap + Superforms + Zod 폼 구성
- Input: 텍스트 입력 필드
- Input Group: 입력 필드에 추가 정보/액션 붙이기
- Input OTP: OTP 입력 (복사/붙여넣기 지원)
- Label: 접근성 레이블
- Native Select: 스타일드 네이티브 select
- Radio Group: 라디오 버튼 그룹 (단일 선택)
- Select: 드롭다운 선택 (버튼 트리거)
- Slider: 범위 값 슬라이더
- Switch: 토글 스위치
- Textarea: 멀티라인 텍스트 입력
Layout & Navigation (레이아웃 & 내비게이션)
- Accordion: 펼치고 접는 아코디언
- Breadcrumb: 현재 위치 경로 표시
- Navigation Menu: 사이트 내비게이션 메뉴
- Resizable: 키보드 지원 리사이저블 패널
- Scroll Area: 커스텀 스크롤 영역
- Separator: 콘텐츠 구분선
- Sidebar: 조합 가능한 사이드바
- Tabs: 탭 패널
Overlays & Dialogs (오버레이 & 다이얼로그)
- Alert Dialog: 확인을 요구하는 모달 다이얼로그
- Command: 커맨드 메뉴 (⌘K 스타일)
- Context Menu: 우클릭 컨텍스트 메뉴
- Dialog: 모달 다이얼로그
- Drawer: 드로어 (모바일 친화적)
- Dropdown Menu: 버튼 트리거 드롭다운 메뉴
- Hover Card: 호버 시 링크 미리보기
- Menubar: 데스크탑 앱 스타일 메뉴바
- Popover: 팝오버
- Sheet: 화면 가장자리 슬라이드 패널
- Tooltip: 호버/포커스 툴팁
Feedback & Status (피드백 & 상태)
- Alert: 알림 박스
- Badge: 배지
- Empty: 빈 상태 표시
- Progress: 진행률 표시바
- Skeleton: 로딩 중 플레이스홀더
- Sonner: 토스트 알림
- Spinner: 로딩 스피너
Display & Media (표시 & 미디어)
- Aspect Ratio: 비율 고정 컨테이너
- Avatar: 사용자 아바타 (폴백 포함)
- Card: 헤더/콘텐츠/푸터 카드
- Carousel: 스와이프 캐러셀 (Embla 기반)
- Chart: 차트 (LayerChart 기반)
- Data Table: 데이터 그리드 (TanStack Table 기반)
- Item: 다목적 콘텐츠 표시
- Kbd: 키보드 입력 표시
- Table: 반응형 테이블
- Typography: 제목/단락/목록 타이포그래피
Misc (기타)
- Collapsible: 접기/펼치기 패널
- Pagination: 페이지네이션
- Range Calendar: 날짜 범위 선택 캘린더
- Toggle: 켜기/끄기 토글 버튼
- Toggle Group: 토글 버튼 그룹