shadcn/ui는 일반적인 npm 패키지가 아닙니다. 컴포넌트 코드를 내 프로젝트에 직접 복사하는 방식입니다. Radix UI + Tailwind CSS 기반이며, 모든 코드를 직접 수정할 수 있습니다.
shadcn/ui 완벽 가이드 — 복붙으로 만드는 UI
Copy-paste 방식의 UI 라이브러리 shadcn/ui 사용법을 정리한다. CLI 설치, 컴포넌트 추가, Tailwind 커스터마이징, 다크 모드 설정과 기존 UI 라이브러리(MUI·Chakra)와의 비교를 포함한다.
한 줄 요약: shadcn/ui는 컴포넌트 라이브러리가 아니라 '복붙 가능한 코드 모음'으로, 소유권이 개발자에게 있어 자유롭게 수정할 수 있다.
Tailwind CSS + Radix UI를 기반으로 한 shadcn/ui는 npm 패키지가 아니라 CLI로 코드를 프로젝트에 직접 복사한다. 이 접근법의 장단점과 실전 활용 패턴을 정리한다.
shadcn/ui란?
shadcn/ui의 핵심 철학은 '코드 소유권'이다. npx shadcn-ui@latest add button을 실행하면 Button 컴포넌트의 전체 소스코드가 components/ui/button.tsx에 복사된다. npm 의존성이 아니므로 업데이트에 의한 breaking change가 없고, 프로젝트 요구에 맞게 자유롭게 수정할 수 있다.
shadcn/ui 초기 설정# 프로젝트 초기화 npx shadcn-ui@latest init # 컴포넌트 추가 npx shadcn-ui@latest add button card dialog npx shadcn-ui@latest add form input label npx shadcn-ui@latest add table dropdown-menu
내부적으로 Radix UI(접근성 보장된 headless 컴포넌트), Tailwind CSS(스타일링), class-variance-authority(CVA)(variant 관리)를 사용한다. 이 조합이 접근성 + 스타일 커스터마이징 + variant 관리를 모두 해결한다.
시작하기
npx shadcn@latest init으로 초기화 → npx shadcn@latest add button으로 필요한 컴포넌트 추가. 추가된 코드는 components/ui/ 폴더에 저장됩니다.
v0와의 시너지
Vercel의 v0에서 생성된 UI는 shadcn/ui 기반입니다. v0에서 디자인 → 코드 복사 → 내 프로젝트에 적용하는 워크플로우가 매우 매끄럽습니다.
커스터마이징 실전 패턴
테마 변경: globals.css의 CSS 변수를 수정하면 전체 테마가 변경된다. --primary, --secondary, --radius 등을 프로젝트 디자인 시스템에 맞게 설정한다. Variant 확장: CVA의 variants 객체에 새로운 variant를 추가하면 <Button variant='custom'>처럼 사용할 수 있다.
다크 모드: components.json에서 cssVariables: true로 설정하면 .dark 클래스 기반 다크 모드가 자동 적용된다. next-themes 라이브러리와 조합하면 시스템 설정 연동까지 간단히 구현된다.
팁: shadcn/ui 공식 사이트의 'Themes' 페이지에서 색상 조합을 미리보고 CSS 변수 코드를 복사할 수 있다. 디자이너와 협업 시 이 도구로 빠르게 프로토타입을 만들어 확인하라.
shadcnui컴포넌트tailwindradix