Theme Playground
Components

Dialog

Dialog는 페이지 위에 모달 형태로 정보를 표시하거나 작업을 수행하도록 하는 컴포넌트입니다.

Import

import { Dialog } from '@vapor-ui/core';

Preview

import { Dialog, Button } from '@vapor-ui/core';

export default function DefaultDialog() {
    return (
        <Dialog.Root>
            <Dialog.Trigger asChild>
                <Button>클릭</Button>
            </Dialog.Trigger>
            <Dialog.CombinedContent>
                <Dialog.Header>
                    <Dialog.Title>알림</Dialog.Title>
                    <Dialog.Close aria-label="Close" />
                </Dialog.Header>
                <Dialog.Body>
                    <Dialog.Description>여기에 다이얼로그 본문 내용이 들어갑니다.</Dialog.Description>
                </Dialog.Body>
                <Dialog.Footer style={{ marginLeft: 'auto' }}>
                    <button style={{ padding: '0.5rem 1rem' }}>확인</button>
                </Dialog.Footer>
            </Dialog.CombinedContent>
        </Dialog.Root>
    );
}

Props

Dialog.Root

이름타입기본값설명
closeOnClickOverlay
booleanundefined
trueOverlay(배경)를 클릭했을 때 다이얼로그가 닫히도록 할지 여부를 결정합니다. false로 설정하면 배경 클릭 시에도 닫히지 않습니다.
closeOnEscape
booleanundefined
trueEscape 키 입력 시 다이얼로그를 닫을지 여부입니다. false로 설정하면 ESC 키를 눌러도 닫히지 않습니다.
size
mdlgxlundefined
md다이얼로그 Content 의 가로 폭을 제어합니다. Root 에 설정하면 모든 Content 에 기본값으로 전달됩니다.
open
booleanundefined
-제어 컴포넌트로서 다이얼로그의 열림 상태를 지정합니다. true 이면 항상 열려 있고, false 이면 닫힌 상태로 유지됩니다.
defaultOpen
booleanundefined
false언컨트롤드 모드에서 다이얼로그의 초기 열림 상태를 설정합니다.
onOpenChange
(open: boolean) => voidundefined
-open 값이 변경될 때 호출되는 콜백 함수입니다.
modal
booleanundefined
truetrue 일 때 모달(dialog) 모드로 포커스가 다이얼로그 바깥으로 이동하지 않습니다. false 로 설정하면 non-modal 상태로 동작합니다.

Dialog.Trigger

이름타입기본값설명
children
React.ReactNode
-다이얼로그를 여는 트리거(버튼) 요소입니다.

Dialog.Content

이름타입기본값설명
onPointerDownOutside
PointerDownOutsideEventundefined
-다이얼로그 외부를 클릭했을 때 호출되는 콜백 함수입니다.
onEscapeKeyDown
KeyboardEventundefined
-Escape 키를 눌렀을 때 호출되는 콜백 함수입니다.

Accessibility Table

Dialog 는 WAI-ARIA Authoring Practices 의 Modal Dialog 패턴을 준수합니다.

개발 시 준수해야 할 내용을 명시합니다.
PropsDescription
aria-labelledby / aria-describedby

Dialog.Title 컴포넌트는 자동으로 role=dialog 요소에 aria-labelledby 를 연결합니다.

Dialog.Description 사용 시 aria-describedby 로 연결되어 스크린리더가 내용을 읽을 수 있습니다.

<Dialog.Root>
  <Dialog.Trigger>Open</Dialog.Trigger>
  <Dialog.CombinedContent>
    <Dialog.Header>
      <Dialog.Title>제목</Dialog.Title>
    </Dialog.Header>
    <Dialog.Body>
      <Dialog.Description>세부 설명</Dialog.Description>
    </Dialog.Body>
  </Dialog.CombinedContent>
</Dialog.Root>
Focus Management

다이얼로그가 열리면 최초 포커스는 다이얼로그 컨텐츠로 이동하고, 닫히면 트리거로 되돌아갑니다.

// 기능은 Radix Dialog 에 의해 자동 처리됩니다.
Keyboard Interactions
InteractionDescription
Escape

포커스가 다이얼로그 안에 있을 때 ESC 키를 누르면 다이얼로그가 닫힙니다. (closeOnEscape=false 인 경우 제외)

Tab

다이얼로그 내부 요소 사이를 순환합니다. 다이얼로그 밖으로 포커스가 벗어나지 않습니다.

Dialog - Vapor UI