Dialog

Dialog는 사용자가 현재 화면의 흐름을 잠시 멈추고 별도의 콘텐츠에 집중해야 할 때 사용해요. Dialog가 열려 있는 동안 포커스는 안에 머물고, 닫히면 다시 원래 버튼으로 돌아와요.

overlay 사이 선택이 헷갈린다면 Overlay Patterns에서 Dialog, AlertDialog, HelpBubble를 먼저 비교해보세요.

Anatomy

Dialog는 Root, Trigger, Content, Title, Description, Close를 중심으로 사용해요. 화면을 덮는 배경은 Content와 함께 보여요.

기본 사용에서는 Dialog.Trigger로 열어요. 라우팅이나 외부 상태와 맞춰야 할 때만 open과 onOpenChange를 함께 사용해요.

Properties

Surface

Dialog는 시스템이 정한 기본 surface 폭을 사용해요. 높이는 콘텐츠에 따라 자연스럽게 늘어나고, 화면보다 길어지면 Dialog 안에서 스크롤돼요.

State

Dialog는 열린 상태와 닫힌 상태를 가져요. 열린 상태에서는 role="dialog"와 aria-modal이 적용돼요. 사용자는 우측 상단 닫기 버튼이나 Escape로 Dialog를 닫을 수 있어야 해요. 각 예제의 trigger를 눌러 실제 열림과 닫힘 흐름을 확인할 수 있어요.

Guidelines

일반 모달 콘텐츠에 사용하기

프로필 정보, 간단한 설정, 보조 흐름처럼 잠시 꺼내 확인하거나 조작해야 하는 콘텐츠에는 Dialog를 사용해요. 삭제나 결제처럼 명시적인 확인이 필요한 흐름이라면 AlertDialog를 사용해요.

다른 overlay와 구분하기

결정을 요구하기보다 콘텐츠를 읽거나 조작하게 하는 쪽에 더 가깝다면 Dialog를 사용해요. Trigger 근처의 짧은 설명에는 HelpBubble을 사용하고, 취소와 확인 중 하나를 분명하게 골라야 한다면 AlertDialog를 사용해요.

제목과 설명을 명확하게 작성하기

제목은 Dialog 안에서 무엇을 할 수 있는지 바로 알 수 있게 써요. 설명은 다음 행동을 판단하는 데 필요한 맥락만 짧게 덧붙여요.

닫는 방법을 예측 가능하게 보여주기

우측 상단 닫기 버튼, Escape처럼 사용자가 떠올릴 수 있는 닫기 방법을 함께 제공해요. 다만 단순히 닫는 것보다 확인이 더 중요한 흐름이라면 Dialog 대신 AlertDialog를 사용해요.

다음에 읽으면 좋은 문서

• overlay 차이는 Overlay Patterns에서 한 번에 비교해요.
• 제목과 설명 문구는 Writing 기준을 따라요.
• 제목과 설명의 텍스트 크기와 계층은 Typography에서 확인해요.
• 명시적인 확인이 필요한 흐름은 AlertDialog에서 확인해요.

Schema