Drawer
화면 가장자리에서 슬라이드되어 나타나는 패널 컴포넌트입니다. 상세 보기·폼·모바일 메뉴·필터·설정 등 보조 UI에 사용하며, 기본 위치는 오른쪽(drawer_placement-right)입니다. 방향별 슬라이드·백드롭 페이드 애니메이션과 role="dialog" · aria-modal 접근성을 제공합니다.
기본
data-drawer-trigger로 패널을 열고, 백드롭·닫기 버튼·Esc로 닫습니다.
Drawer 패널 본문입니다. 상세 정보·폼·설정 등 보조 작업에 적합합니다.
백드롭을 클릭하거나 닫기 버튼, Esc 키로 패널을 닫을 수 있습니다.
위치
drawer_placement-left · -right · -top · -bottom으로 슬라이드 방향을 지정합니다. 상·하는 둥근 모서리·하단은 드래그 핸들이 표시됩니다.
화면 왼쪽에서 슬라이드됩니다.
기본 위치입니다. 상세 보기·편집 폼에 자주 사용합니다.
검색·필터 바 등 상단에서 내려오는 패널입니다.
모바일 액션 시트·공유 패널 등에 적합합니다.
크기
drawer_sm · drawer_lg으로 패널 너비(또는 상·하 배치 시 높이)를 조정합니다.
drawer_sm — 좁은 보조 패널
기본 너비 24rem
drawer_lg — 넓은 상세·폼 패널
헤더·푸터
drawer_header · drawer_body · drawer_footer로 영역을 나눕니다. 푸터에 저장·취소 등 액션 버튼을 배치합니다.
푸터 정렬
footerAlign으로 푸터 버튼을 정렬합니다. start · center · end(기본) · between(좌·우 병합) · even(균등). even은 footerRatio로 좌·우 비율(1-1 · 1-2 · 2-1)을 지정하고, footerNoPadBottom으로 하단 패딩을 제거할 수 있습니다. between은 drawer_footer-group으로 좌·우에 1~2개씩 묶습니다.
헤더 추가 영역
drawer_extra에 보조 액션·메타 정보를 배치합니다. 제목과 닫기 버튼 사이에 위치합니다.
상세 정보·상태 뱃지 등을 헤더 drawer_extra에 배치할 수 있습니다.
메뉴
Menu 컴포넌트와 조합해 모바일 내비게이션 패널을 구성합니다.
로드 시 자동 열기 (옵션)
data-drawer-open-on-load="true"를 지정하면 페이지 로드 후 해당 Drawer를 자동으로 열 수 있습니다. 기본값은 비활성입니다. (Docs에서는 미리보기를 가리지 않도록 수동 트리거로 확인합니다.)
openOnLoad / data-drawer-open-on-load="true" — 가이드 페이지에서 자동 열기를 확인할 수 있습니다.
실서비스에서는 온보딩·공지 등에 openOnLoad를 사용합니다.
중첩 Drawer
열린 Drawer 안에서 다른 Drawer를 열 수 있습니다. 2단계가 열리면 1단계 백드롭은 숨겨지고, 2단계가 닫히면 다시 표시됩니다. Esc는 가장 위에 열린 패널부터 닫습니다.
다음 단계 Drawer를 열어 중첩 동작을 확인하세요.
중첩된 Drawer입니다. Esc를 누르면 이 패널부터 닫힙니다.
하단 드래그 시트
placement="bottom" + draggable로 핸들·헤더를 드래그합니다. 위로 끌면 펼치고, 아래로 끌면 접거나 닫습니다. 터치 슬라이드도 동일합니다.
핸들 또는 제목 영역을 위·아래로 드래그(터치 슬라이드)해 보세요.
상단 핸들이나 헤더를 위로 드래그하면 시트가 펼쳐집니다.
아래로 드래그하면 기본 높이로 접히고, 더 내리면 닫힙니다.
- 링크 복사
- 메시지 보내기
- 다른 앱으로 공유
백드롭 없음
data-drawer-backdrop="false"로 어두운 배경을 숨깁니다. 본문과 동시에 상호작용할 수 있습니다.
본문을 가리지 않고 패널만 표시합니다. 닫기 버튼이나 Esc로 닫으세요.
마크업
트리거 버튼과 Drawer 루트를 id · aria-controls로 연결합니다. 기본은 닫힌 상태(hidden)이며, 클릭 이벤트로 열립니다.
<!-- 트리거 -->
<button type="button" data-drawer-trigger="#drawer-1"
aria-controls="drawer-1" aria-expanded="false">
Drawer 열기
</button>
<!-- Drawer -->
<div class="drawer" id="drawer-1" data-drawer
role="dialog" aria-modal="true" aria-labelledby="drawer-1-title"
tabindex="-1" hidden>
<div class="drawer_backdrop" data-drawer-close aria-hidden="true"></div>
<div class="drawer_panel drawer_placement-right">
<div class="drawer_header">
<h2 class="drawer_title" id="drawer-1-title">제목</h2>
<div class="drawer_extra">…</div>
<button type="button" class="drawer_close"
data-drawer-close aria-label="닫기">…</button>
</div>
<div class="drawer_body">본문</div>
<div class="drawer_footer">
<button type="button" class="btn btn_ghost" data-drawer-close>취소</button>
<button type="button" class="btn btn_filled color_primary" data-drawer-close>저장</button>
</div>
</div>
</div>
<!-- 푸터 정렬: start · center · end · between · even -->
<!-- 균등 비율: drawer_footer-even · drawer_footer-even-1-2 · drawer_footer-even-2-1 -->
<!-- 하단 패딩 없음: drawer_footer-no-pad-b (+ even 권장) -->
<div class="drawer_footer drawer_footer-even drawer_footer-no-pad-b">
<button type="button" class="btn btn_ghost" data-drawer-close>취소</button>
<button type="button" class="btn btn_filled color_primary" data-drawer-close>확인</button>
</div>
<!-- 옵션: 백드롭 없음 -->
<div class="drawer" id="drawer-plain" data-drawer
data-drawer-backdrop="false" …>…</div>
<!-- 옵션: 로드 시 자동 열기 -->
<div class="drawer" id="drawer-onboard" data-drawer
data-drawer-open-on-load="true" …>…</div>
<!-- 옵션: 하단 드래그 시트 -->
<div class="drawer" id="drawer-sheet" data-drawer
data-drawer-draggable="true" …>
<div class="drawer_panel drawer_placement-bottom drawer_draggable">
<div class="drawer_handle" data-drawer-drag-handle aria-hidden="true">
<span class="drawer_handle-bar"></span>
</div>
…
</div>
</div>API · Props
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
id | string | — | 루트 id (필수) |
title | string | — | 패널 제목 (drawer_title) |
size | 'sm' | 'md' | 'lg' | md | drawer_sm · drawer_lg |
placement | 'left' | 'right' | 'top' | 'bottom' | right | drawer_placement-* |
noBackdrop | boolean | false | data-drawer-backdrop="false" |
openOnLoad | boolean | false | data-drawer-open-on-load="true" |
draggable | boolean | false | 하단 패널 핸들·헤더 드래그 펼침/접힘 (placement="bottom", data-drawer-draggable) |
open | boolean | false | 열림 상태 (is-open) |
footerAlign | 'start' | 'center' | 'end' | 'between' | 'even' | end | 푸터 정렬 (drawer_footer-start · center · between · even). between은 drawer_footer-group으로 좌·우 묶음 |
footerRatio | '1-1' | '1-2' | '2-1' | 1-1 | 균등 정렬(even) 좌·우 비율 (drawer_footer-even-1-2 · even-2-1) |
footerNoPadBottom | boolean | false | 푸터 하단 패딩 제거 (drawer_footer-no-pad-b). even과 함께 쓰면 좌우 패딩·간격도 제거 |
header | ReactNode | — | 커스텀 헤더 (title 대체) |
extra | ReactNode | — | 헤더 보조 영역 (drawer_extra) |
footer | ReactNode | — | 하단 액션 영역 (drawer_footer) |
className | string | — | drawer 루트에 추가 클래스 |
ripple | boolean | true | 클릭 파장(ripple). 닫기·트리거 버튼에 적용 · true 활성 · false 비활성 |
API · Children
| Children | 설명 |
|---|---|
header | 헤더 (title 대체) |
extra | 헤더 보조 영역 (drawer_extra) |
children | 본문 (drawer_body, Vue default 슬롯 대응) |
footer | 하단 액션 (drawer_footer) |
클래스 · 속성
React 컴포넌트가 렌더하는 OOCSS 클래스입니다. HTML 마크업으로 직접 작성할 때 동일하게 조합합니다.
| 클래스 | 설명 |
|---|---|
drawer · drawer_backdrop · drawer_panel | 루트·백드롭·패널 |
drawer_header · drawer_title · drawer_extra · drawer_close | 헤더 파트 |
drawer_body · drawer_footer | 본문·푸터 |
drawer_footer-start · drawer_footer-center · drawer_footer-end · drawer_footer-between · drawer_footer-even | 푸터 정렬 (기본 end) |
drawer_footer-even-1-2 · drawer_footer-even-2-1 | 균등 정렬 좌·우 비율 (기본 1:1) |
drawer_footer-no-pad-b | 푸터 하단 패딩 없음 (even 조합 시 좌우 패딩·간격 제거) |
drawer_footer-group | 병합 정렬용 좌·우 버튼 묶음 |
drawer_placement-left · drawer_placement-right · drawer_placement-top · drawer_placement-bottom | 슬라이드 방향 |
drawer_sm · drawer_lg | 패널 크기 |
drawer_handle · drawer_handle-bar · drawer_draggable | 하단 드래그 핸들 |
data-drawer · data-drawer-trigger · data-drawer-close | JS 연동 속성 |
data-drawer-open-on-load | 페이지 로드 후 자동 열기 |
data-drawer-draggable · data-drawer-drag-handle | 하단 드래그 펼침/접힘 |
is-open · is-opening · is-closing · is-stack-covered · is-expanded · is-dragging · hidden | 열림·닫힘·중첩 하위(백드롭 숨김)·드래그·애니메이션 상태 |
data-ripple | 클릭 파장 활성. data-ripple="surface"는 절대 위치 보조 버튼용 |
data-ripple="false" | 해당 요소 ripple 비활성 |
data-no-ripple | 하위 전체 ripple 비활성 |
닫기: 백드롭 · data-drawer-close · Esc. 열기·닫기 시 방향별 슬라이드와 백드롭 페이드가 적용됩니다. 중첩 시 Esc는 최상위 패널부터 닫습니다.
디자인 토큰
| 토큰 | 기본값 | 설명 |
|---|---|---|
--drawer-z-index | 250 | 레이어 순서 |
--drawer-width · --drawer-width-sm · --drawer-width-lg | 24rem · 18rem · 36rem | 좌·우 패널 너비 |
--drawer-height · --drawer-height-sm · --drawer-height-lg | 18rem · 14rem · 26rem | 상·하 패널 높이 |
--drawer-height-expanded | 90% | 하단 드래그 펼침 높이 |
--drawer-panel-duration-x · --drawer-panel-duration-y | 0.32s · 0.36s | 좌·우 / 상·하 슬라이드 시간 |
--drawer-panel-easing-x · --drawer-panel-easing-y | cubic-bezier(0.32, 0.72, 0, 1) · cubic-bezier(0.33, 1, 0.68, 1) | 방향별 이징 |