AlertDialog

AlertDialog는 삭제, 이탈, 되돌릴 수 없는 변경처럼 사용자가 결과를 이해하고 직접 결정해야 하는 상황에서 사용해요. 일반 Dialog와 달리 우측 상단 닫기 버튼보다, 본문 아래 액션에서 취소와 확인을 고르게 해요.

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

Anatomy

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

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

Properties

Surface

AlertDialog는 별도의 크기 선택 없이 시스템이 정한 기본 surface 폭을 사용해요. 확인 문구가 길어져 넓은 레이아웃이 필요하다면 일반 Dialog나 별도 확인 흐름을 먼저 고려해요.

State

AlertDialog는 열린 상태와 닫힌 상태를 가져요. 열린 상태에서는 role="alertdialog"와 aria-modal이 적용돼요. 포커스는 사용자가 선택할 수 있는 안전한 액션으로 이동해야 하고, 기본값으로는 바깥을 눌러도 바로 닫히지 않아요. 각 예제의 trigger를 눌러 실제 열림과 닫힘 흐름을 확인할 수 있어요.

Action Pattern

AlertDialog의 액션은 사용자가 결정을 끝낼 수 있을 만큼만 남겨요. 단순 확인에는 액션 1개만 둘 수 있고, 되돌리기 어려운 작업에는 취소와 위험 액션을 함께 보여줘요.

Single Action

Single Action은 사용자가 내용을 확인하기만 하면 되는 흐름에 사용해요. 취소와 확인 중 하나를 고르게 할 필요가 없다면 액션 1개만 남겨요.

Danger Action

Danger Action은 삭제, 초기화처럼 되돌리기 어려운 결과를 확인할 때 사용해요. 안전하게 빠져나갈 수 있는 취소 액션과 결과를 직접 말하는 위험 액션을 함께 보여줘요.

Guidelines

명시적인 결정이 필요한 상황에서 사용하기

삭제, 저장하지 않은 변경사항 이탈, 중요한 설정 변경처럼 결과가 크거나 되돌리기 어려운 상황에서 사용해요. 단순 안내나 짧은 피드백이라면 AlertDialog보다 가벼운 컴포넌트를 먼저 고려해요.

다른 overlay와 구분하기

사용자가 내용을 본 뒤 그냥 닫아도 되는 경우라면 AlertDialog 대신 Dialog를 사용해요. Trigger 근처에서 짧은 보조 설명만 보여주면 충분하다면 HelpBubble을 사용해요. AlertDialog는 결정 자체가 핵심일 때 사용해요.

우측 상단 닫기 버튼 두지 않기

AlertDialog는 사용자가 취소와 확인 중 하나를 분명하게 선택해야 하는 패턴이에요. 그래서 우측 상단 X 버튼보다 하단 액션으로 닫기 흐름을 제공해요.

바깥 클릭으로 바로 닫히지 않게 두기

AlertDialog는 실수로 닫히면 안 되는 확인 흐름에 사용해요. 그래서 기본값으로는 바깥을 눌러도 닫히지 않게 두고, 취소나 확인 액션으로 닫아요.

제목과 설명을 결정 중심으로 작성하기

제목은 사용자가 무엇을 결정해야 하는지 바로 알 수 있게 써요. 필요하다면 질문형을 사용할 수 있어요. 설명은 확인했을 때 생기는 결과나 되돌리기 어려운 영향을 알려줘요.

다음에 읽으면 좋은 문서

• overlay 차이는 Overlay Patterns에서 한 번에 비교해요.
• 확인/취소 액션에 쓰는 버튼 위계는 Button에서 확인해요.
• 제목과 설명 문구는 Writing 기준을 따라요.
• 제목과 설명의 텍스트 크기와 계층은 Typography에서 확인해요.

Schema