Skip to Content
ComponentsFoundationDrawer

Drawer

화면 가장자리에서 슬라이드되어 나타나는 패널 컴포넌트

개요

Drawer 컴포넌트는 vaul 기반으로 화면의 상/하/좌/우 가장자리에서 슬라이드되어 나타나는 패널을 제공합니다. 모바일 환경의 바텀 시트나 사이드 패널 UI에 적합하며, 스와이프 제스처로 닫기를 지원합니다.

주요 특징

  • ✅ 4방향 지원: top, bottom, left, right 방향으로 열기
  • ✅ 스와이프 닫기: 드래그 제스처로 자연스럽게 닫기
  • ✅ 구조화된 레이아웃: DrawerHeader, DrawerFooter 제공
  • ✅ 닫기 버튼: showCloseButton으로 우측 상단 닫기 버튼 표시
  • ✅ 오버레이: 배경 딤 처리와 블러 효과
  • ✅ 디자인 토큰: 테마 커스터마이징 지원

사용 예시

기본 사용

기본적으로 화면 하단에서 올라오는 바텀 시트입니다.

방향 지정

direction으로 Drawer가 열리는 방향을 지정합니다.

닫기 버튼 표시

showCloseButton으로 우측 상단에 닫기 버튼을 표시합니다.

API Reference

Drawer Props

vaul의 Drawer.Root props를 상속합니다.

PropTypeDefaultDescription
direction"top" | "bottom" | "left" | "right""bottom"Drawer가 열리는 방향
openboolean-열림 상태 (제어 모드)
onOpenChange(open: boolean) => void-열림 상태 변경 콜백
dismissiblebooleantrue오버레이 클릭/스와이프로 닫기
modalbooleantrue모달 동작 여부 (배경 차단)

DrawerContent Props

Portal과 Overlay를 포함하여 렌더링합니다.

PropTypeDefaultDescription
showCloseButtonbooleanfalse우측 상단 닫기 버튼 표시
classNamestring-추가 CSS 클래스

DrawerTrigger / DrawerClose Props

PropTypeDefaultDescription
asChildbooleanfalse자식 요소를 트리거로 사용

기본 사용법

import {
  Drawer,
  DrawerTrigger,
  DrawerContent,
  DrawerHeader,
  DrawerFooter,
  DrawerTitle,
  DrawerDescription,
  DrawerClose,
} from "@vortex/ui-foundation"
 
<Drawer>
  <DrawerTrigger asChild>
    <Button variant="outline">열기</Button>
  </DrawerTrigger>
  <DrawerContent>
    <DrawerHeader>
      <DrawerTitle>제목</DrawerTitle>
      <DrawerDescription>설명</DrawerDescription>
    </DrawerHeader>
    <div className="p-4">본문 콘텐츠</div>
    <DrawerFooter>
      <DrawerClose asChild>
        <Button variant="outline">닫기</Button>
      </DrawerClose>
    </DrawerFooter>
  </DrawerContent>
</Drawer>

접근성

시맨틱 마크업

  • vaul 기반으로 role="dialog" 자동 적용
  • DrawerTitle이 aria-labelledby, DrawerDescription이 aria-describedby로 자동 연결
  • 열린 동안 배경 콘텐츠가 보조 기술에서 숨김 처리

키보드 및 제스처

  • ✅ Esc로 Drawer 닫기
  • ✅ 포커스 트랩: Tab 순환이 Drawer 내부로 제한
  • ✅ 스와이프(드래그) 제스처로 닫기 지원
  • ⚠️ DrawerDescription을 생략할 경우 aria-describedby={undefined}를 명시해야 경고가 발생하지 않습니다

관련 컴포넌트

  • Dialog: 화면 중앙에 표시되는 모달 대화 상자
  • Modal: bottomsheet 타입을 포함한 모달 컴포넌트
  • DropdownMenu: 트리거 기반 간단 메뉴
Last updated on
DialogDropdownMenu