Dialog

Dialog는 사용자의 주요 작업 흐름을 방해하지 않으면서 정보를 표시하거나 사용자 입력을 받는 모달 컴포넌트입니다. Radix UI의 Dialog 컴포넌트를 기반으로 구현되었습니다.

접근성이 고려된 모달 다이얼로그를 쉽게 구현할 수 있습니다
헤더, 본문, 푸터를 구조화된 방식으로 제공합니다
애니메이션 효과와 오버레이를 포함합니다

Installation

npx @jongh/cli add dialog

Usage

Dialog는 Radix UI의 컴포넌트를 기반으로 구현되었으며, 여러 하위 컴포넌트로 구성됩니다.

컴포넌트 구조

Dialog.Root: 다이얼로그의 모든 파트를 감싸는 컨테이너입니다.
Dialog.Trigger: 다이얼로그를 여는 버튼입니다.
Dialog.Portal: 다이얼로그를 DOM의 최상위 레벨로 포탈링합니다.
Dialog.Overlay: 다이얼로그 뒤의 오버레이입니다.
Dialog.Content: 다이얼로그의 내용을 담는 컨테이너입니다.
Dialog.Header: 다이얼로그의 헤더 영역입니다.
Dialog.Footer: 다이얼로그의 푸터 영역입니다.
Dialog.Title: 다이얼로그의 제목을 표시합니다.
Dialog.Description: 다이얼로그의 설명 텍스트를 표시합니다.
Dialog.Close: 다이얼로그를 닫는 버튼입니다 (Content에 자동으로 포함됨).

Props

Dialog.Root

Prop	Type	Description
`defaultOpen`	`boolean`	초기 렌더링 시 다이얼로그의 열림 상태를 설정합니다.
`open`	`boolean`	다이얼로그의 표시 여부를 제어합니다.
`onOpenChange`	`(open: boolean) => void`	다이얼로그의 표시 상태가 변경될 때 호출될 콜백 함수입니다.
`modal` Default: `true`	`boolean`	모달 모드 활성화 여부를 설정합니다.

Dialog.Trigger

Prop	Type	Description
`asChild` Default: `false`	`boolean`	트리거 요소를 자식 요소로 대체합니다.

Dialog.Portal

Prop	Type	Description
`forceMount`	`boolean`	포탈 컴포넌트를 강제로 마운트합니다.
`container`	`HTMLElement`	포탈링할 컨테이너 요소를 지정합니다.

Dialog.Overlay

Prop	Type	Description
`forceMount`	`boolean`	오버레이 컴포넌트를 강제로 마운트합니다.
`asChild` Default: `false`	`boolean`	오버레이 요소를 자식 요소로 대체합니다.

Dialog.Content

Prop	Type	Description
`forceMount`	`boolean`	컨텐츠 컴포넌트를 강제로 마운트합니다.
`asChild` Default: `false`	`boolean`	컨텐츠 요소를 자식 요소로 대체합니다.
`onOpenAutoFocus`	`(event: Event) => void`	다이얼로그가 열릴 때 자동 포커스 이벤트를 처리합니다.
`onCloseAutoFocus`	`(event: Event) => void`	다이얼로그가 닫힐 때 자동 포커스 이벤트를 처리합니다.
`onEscapeKeyDown`	`(event: KeyboardEvent) => void`	ESC 키가 눌렸을 때 이벤트를 처리합니다.
`onPointerDownOutside`	`(event: PointerDownOutsideEvent) => void`	외부 클릭 이벤트를 처리합니다.
`onInteractOutside`	`(event: InteractOutsideEvent) => void`	외부 상호작용 이벤트를 처리합니다.

Dialog.Title

Prop	Type	Description
`asChild` Default: `false`	`boolean`	제목 요소를 자식 요소로 대체합니다.

Dialog.Description

Prop	Type	Description
`asChild` Default: `false`	`boolean`	설명 요소를 자식 요소로 대체합니다.

Dialog.Close

Prop	Type	Description
`asChild` Default: `false`	`boolean`	닫기 버튼 요소를 자식 요소로 대체합니다.

Accessibility

Dialog 컴포넌트는 WAI-ARIA Dialog Modal 디자인 패턴을 따르고 있습니다.

Dialog.Content에는 자동으로 role="dialog"와 aria-modal="true"가 설정됩니다.
Dialog.Title의 ID가 Dialog.Content의 aria-labelledby 속성에 자동으로 연결됩니다.
Dialog.Description의 ID가 Dialog.Content의 aria-describedby 속성에 자동으로 연결됩니다.
ESC 키를 누르면 다이얼로그가 닫힙니다.

Example

기본 사용 예시

import * as Dialog from "@/components/dialog"

const DialogExample = () => (
  <Dialog.Root>
    <Dialog.Trigger>다이얼로그 열기</Dialog.Trigger>
    <Dialog.Content>
      <Dialog.Header>
        <Dialog.Title>다이얼로그 제목</Dialog.Title>
        <Dialog.Description>
          여기에 다이얼로그의 설명 내용을 작성합니다. 사용자에게 필요한 정보나
          안내 사항을 제공할 수 있습니다.
        </Dialog.Description>
      </Dialog.Header>
      <div>
        {/* 다이얼로그의 본문 내용 */}
        <div className="textStyle_body1">
          다이얼로그의 본문 내용을 여기에 넣습니다.
        </div>
      </div>
      <Dialog.Footer>
        <button>확인</button>
      </Dialog.Footer>
    </Dialog.Content>
  </Dialog.Root>
)

제어 컴포넌트로 사용하는 예시

import * as Dialog from "@/components/dialog"
import { useState } from "react"

const ControlledDialogExample = () => {
  const [open, setOpen] = useState(false)

  return (
    <>
      <button onClick={() => setOpen(true)}>다이얼로그 열기</button>

      <Dialog.Root open={open} onOpenChange={setOpen}>
        <Dialog.Content>
          <Dialog.Header>
            <Dialog.Title>제어 컴포넌트 예시</Dialog.Title>
            <Dialog.Description>
              상태를 통해 다이얼로그를 제어합니다.
            </Dialog.Description>
          </Dialog.Header>
          <Dialog.Footer>
            <button onClick={() => setOpen(false)}>닫기</button>
            <button>확인</button>
          </Dialog.Footer>
        </Dialog.Content>
      </Dialog.Root>
    </>
  )
}

더 자세한 내용

더 자세한 내용은 Radix UI Dialog 공식 문서를 참조하세요.