Sidebar
애플리케이션 내비게이션을 위한 접이식 사이드바 컴포넌트
개요
Sidebar 컴포넌트는 애플리케이션의 주요 내비게이션 레이아웃을 구성하는 Compound 컴포넌트입니다. SidebarProvider로 상태를 관리하며, 데스크톱에서는 접이식 사이드바로, 모바일에서는 Sheet 기반 오프캔버스 메뉴로 동작합니다.
주요 특징
- ✅ 다양한 Variant: sidebar, floating, inset 레이아웃 지원
- ✅ 접기 방식: offcanvas, icon, none 접기 모드 지원
- ✅ 반응형: 모바일에서 Sheet 기반 사이드바로 자동 전환
- ✅ 풍부한 서브컴포넌트: Header, Footer, Group, Menu, Sub 메뉴 등 20개 이상
- ✅ 키보드 단축키:
Cmd/Ctrl + B로 사이드바 토글 - ✅ 상태 유지: 쿠키에 열림 상태 저장 (7일)
- ✅ 디자인 토큰: 테마 커스터마이징 지원
기본 구조
SidebarProvider로 감싸고 Sidebar 내부에 Header, Content, Footer를 조합합니다. 아래는 collapsible="none"으로 고정된 정적 예시입니다.
Preview
Variant와 접기 모드
variant와 collapsible prop으로 사이드바의 형태와 접기 동작을 제어합니다.
| Prop | 값 | 설명 |
|---|---|---|
variant | "sidebar" (기본) | 일반 사이드바 |
"floating" | 둥근 모서리와 그림자가 있는 플로팅 형태 | |
"inset" | 메인 콘텐츠 안에 삽입된 형태 | |
collapsible | "offcanvas" (기본) | 접으면 화면 밖으로 완전히 숨김 |
"icon" | 접으면 아이콘만 표시 | |
"none" | 접기 없이 항상 고정 |
API Reference
SidebarProvider
| Prop | Type | Default | Description |
|---|---|---|---|
defaultOpen | boolean | true | 비제어 모드 초기 열림 상태 |
open | boolean | - | 제어 모드 열림 상태 |
onOpenChange | (open: boolean) => void | - | 열림 상태 변경 콜백 |
Sidebar
| Prop | Type | Default | Description |
|---|---|---|---|
side | "left" | "right" | "left" | 사이드바 위치 |
variant | "sidebar" | "floating" | "inset" | "sidebar" | 레이아웃 variant |
collapsible | "offcanvas" | "icon" | "none" | "offcanvas" | 접기 방식 |
className | string | - | 추가 CSS 클래스 |
SidebarMenuButton
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "default" | "outline" | "default" | 버튼 스타일 |
size | "default" | "sm" | "lg" | "default" | 버튼 크기 |
isActive | boolean | false | 활성 상태 표시 |
tooltip | string | TooltipContent props | - | 아이콘 모드로 접혔을 때 표시할 툴팁 |
render | ReactElement | - | 렌더링할 요소 대체 (예: <a>) |
기타 서브컴포넌트
| Component | 역할 |
|---|---|
SidebarTrigger | 사이드바 토글 버튼 (PanelLeft 아이콘) |
SidebarRail | 사이드바 가장자리 토글 핸들 |
SidebarInset | 사이드바 옆 메인 콘텐츠 영역 (<main>) |
SidebarHeader | 사이드바 상단 영역 |
SidebarFooter | 사이드바 하단 영역 |
SidebarContent | 스크롤 가능한 본문 영역 |
SidebarGroup | 메뉴 그룹 컨테이너 |
SidebarGroupLabel | 그룹 라벨 |
SidebarGroupAction | 그룹 우측 액션 버튼 |
SidebarGroupContent | 그룹 콘텐츠 영역 |
SidebarInput | 사이드바 검색 입력 필드 |
SidebarSeparator | 그룹 사이 구분선 |
SidebarMenu | 메뉴 리스트 (<ul>) |
SidebarMenuItem | 메뉴 항목 (<li>) |
SidebarMenuAction | 항목 우측 액션 버튼 (showOnHover 지원) |
SidebarMenuBadge | 항목 우측 배지 |
SidebarMenuSkeleton | 로딩 스켈레톤 (showIcon 지원) |
SidebarMenuSub | 서브 메뉴 리스트 |
SidebarMenuSubItem | 서브 메뉴 항목 |
SidebarMenuSubButton | 서브 메뉴 버튼 (size: "sm" | "md" 지원) |
기본 사용법
import {
SidebarProvider,
Sidebar,
SidebarTrigger,
SidebarInset,
} from "@vortex/ui-foundation"
<SidebarProvider>
<Sidebar variant="sidebar" collapsible="icon">{/* ... */}</Sidebar>
<SidebarInset>
<header>
<SidebarTrigger />
</header>
<main>{/* 페이지 콘텐츠 */}</main>
</SidebarInset>
</SidebarProvider>접근성
키보드 지원
Cmd/Ctrl + B단축키로 사이드바 토글- SidebarTrigger와 SidebarRail에
aria-label="Toggle Sidebar"적용
시맨틱 마크업
- SidebarInset이
<main>요소로 렌더링되어 랜드마크 제공 - 모바일에서는 Sheet(Dialog) 기반으로 포커스 트랩과
role="dialog"적용 - 메뉴는
<ul>,<li>시맨틱 리스트 구조 사용
권장 사항
- ✅ 현재 페이지 메뉴에
isActive적용 - ✅ icon 모드에서
tooltipprop으로 메뉴명 제공 - ❌ SidebarProvider 없이 Sidebar 하위 컴포넌트 단독 사용 금지 (
useSidebar에러 발생)