Dialog
사용자의 확인이나 입력을 받는 모달 대화 상자 컴포넌트
개요
Dialog 컴포넌트는 base-ui의 Dialog Primitive를 기반으로 화면 중앙에 오버레이 대화 상자를 표시합니다. 헤더/본문/푸터 구조, 드래그 이동, 크기 조절 등 확장 기능을 제공합니다.
주요 특징
- ✅ 구조화된 레이아웃: DialogHeader, DialogBody, DialogFooter 제공
- ✅ 닫기 버튼: showCloseButton으로 우측 상단 닫기 버튼 표시 (기본 활성)
- ✅ 드래그 이동: draggable로 헤더 드래그 시 위치 이동
- ✅ 크기 조절: resizable로 8방향 리사이즈 핸들 제공
- ✅ 위치 유지: preservePosition으로 일시 숨김 시 위치/크기 보존
- ✅ 디자인 토큰: 테마 커스터마이징 지원
사용 예시
기본 사용
트리거를 클릭하면 다이얼로그가 열립니다.
Preview
긴 내용 (바디만 스크롤)
내용이 길어도 DialogHeader / DialogFooter 는 고정되고 DialogBody 영역만 스크롤됩니다. 다이얼로그 전체 높이는 calc(100dvh - 2rem) 을 넘지 않습니다.
Preview
드래그 가능한 다이얼로그
draggable을 활성화하면 헤더를 드래그하여 다이얼로그 위치를 이동할 수 있습니다.
Preview
크기 조절 가능한 다이얼로그
resizable을 활성화하면 모서리와 가장자리의 핸들로 크기를 조절할 수 있습니다.
Preview
API Reference
Dialog Props
base-ui Dialog Root의 props를 상속합니다.
| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | - | 열림 상태 (제어 모드) |
defaultOpen | boolean | false | 초기 열림 상태 (비제어 모드) |
onOpenChange | (open: boolean) => void | - | 열림 상태 변경 콜백 |
modal | boolean | true | 모달 동작 여부 (배경 차단) |
DialogContent Props
Portal과 Overlay를 포함하여 렌더링합니다.
| Prop | Type | Default | Description |
|---|---|---|---|
showCloseButton | boolean | true | 우측 상단 닫기 버튼 표시 |
draggable | boolean | false | 헤더 드래그로 위치 이동 활성화 |
resizable | boolean | false | 8방향 리사이즈 핸들 활성화 |
preservePosition | boolean | false | 일시 숨김 시 드래그/리사이즈 상태 유지 |
initialFocus | Ref | - | 열릴 때 초기 포커스를 받을 요소 |
className | string | - | 추가 CSS 클래스 |
DialogBody Props
| Prop | Type | Default | Description |
|---|---|---|---|
scrollable | boolean | true | 바디 영역만 스크롤 (헤더/푸터는 고정) |
className | string | - | 추가 CSS 클래스 |
바디 스크롤 동작
DialogContent 는 flex flex-col + max-height: calc(100dvh - 2rem) 이고, DialogBody 만 스크롤 컨테이너입니다. 따라서 내용이 길어져도
- 다이얼로그가 뷰포트를 넘지 않고,
DialogHeader/DialogFooter는 화면에 고정된 채 바디 영역만 스크롤됩니다.
내용 전체가 잘려도 무방한 경우에만 <DialogBody scrollable={false}> 로 끕니다.
DialogTrigger / DialogClose Props
| Prop | Type | Default | Description |
|---|---|---|---|
render | ReactElement | - | 트리거로 렌더링할 요소 (base-ui) |
DialogFooter Props
| Prop | Type | Default | Description |
|---|---|---|---|
showCloseButton | boolean | false | 푸터에 닫기 버튼 추가 |
className | string | - | 추가 CSS 클래스 |
기본 사용법
import {
Dialog,
DialogTrigger,
DialogContent,
DialogHeader,
DialogBody,
DialogFooter,
DialogTitle,
DialogDescription,
DialogClose,
} from "@vortex/ui-foundation"
<Dialog>
<DialogTrigger render={<Button />}>열기</DialogTrigger>
<DialogContent>
<DialogHeader>
<DialogTitle>제목</DialogTitle>
<DialogDescription>설명</DialogDescription>
</DialogHeader>
<DialogBody>본문 콘텐츠</DialogBody>
<DialogFooter>
<DialogClose render={<Button variant="outline" />}>닫기</DialogClose>
</DialogFooter>
</DialogContent>
</Dialog>접근성
시맨틱 마크업
- base-ui Dialog 기반으로
role="dialog"와aria-modal자동 적용 - DialogTitle이
aria-labelledby, DialogDescription이aria-describedby로 자동 연결 - 열린 동안 배경 콘텐츠가 보조 기술에서 숨김 처리
키보드 지원
- ✅
Esc로 다이얼로그 닫기 - ✅ 열릴 때 다이얼로그 내부로 포커스 이동 (initialFocus로 지정 가능)
- ✅ 포커스 트랩:
Tab순환이 다이얼로그 내부로 제한 - ✅ 닫힐 때 트리거로 포커스 복귀
관련 컴포넌트
Last updated on