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

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

Dialog.Trigger

• asChild (boolean): 트리거 요소를 자식 요소로 대체합니다. 기본값은 false입니다.

Dialog.Portal

• forceMount (boolean): 포탈 컴포넌트를 강제로 마운트합니다.
• container (HTMLElement): 포탈링할 컨테이너 요소를 지정합니다.

Dialog.Overlay

• forceMount (boolean): 오버레이 컴포넌트를 강제로 마운트합니다.
• asChild (boolean): 오버레이 요소를 자식 요소로 대체합니다. 기본값은 false입니다.

Dialog.Content

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

Dialog.Title

• asChild (boolean): 제목 요소를 자식 요소로 대체합니다. 기본값은 false입니다.

Dialog.Description

• asChild (boolean): 설명 요소를 자식 요소로 대체합니다. 기본값은 false입니다.

Dialog.Close

• asChild (boolean): 닫기 버튼 요소를 자식 요소로 대체합니다. 기본값은 false입니다.

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 공식 문서를 참조하세요.