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: 토글 버튼 그룹

sveltekit-shadcn-guidline