Get StartedFoundationsComponentsPatternsRulesDevelopAI & ToolsUpdates

Dialog

사용자의 흐름을 잠시 멈추고 중요한 정보를 전달하거나 작업을 완료하도록 하는 모달형 컴포넌트예요.

Alert Dialog

사용자의 즉각적인 확인이나 경고가 필요하다면 Alert Dialog를 사용해요. 두 컴포넌트의 차이는 아래 Dialog vs Alert Dialog 섹션을 참고해요.

설치

pnpm dlx shadcn@latest add https://rebar.conmarket-landing.workers.dev/r/dialog.json

Anatomy

Dialog는 Backdrop 위에 Header · Body · Footer 세 영역으로 구성돼요.

  • Header: Dialog의 제목과 설명을 제공하며, 필요한 경우 닫기 버튼을 포함해요.
  • Body: 실제 콘텐츠가 배치되는 영역이에요. 내용이 길면 이 영역만 스크롤돼요.
  • Footer: 작업을 완료하거나 취소하는 액션 버튼이 배치돼요.
  • Backdrop: Dialog 뒤쪽의 메인 화면을 어둡게 처리해 시선을 집중시켜요.
<Dialog>
  <DialogTrigger />
  <DialogContent title="제목" description="설명">
    <DialogBody />
    <DialogFooter>
      <DialogAction />
    </DialogFooter>
  </DialogContent>
</Dialog>

title, description 대신 DialogHeader, DialogTitle, DialogDescription 을 직접 조합할 수도 있어요.

Properties

Size

데스크톱 환경을 기준으로 두 가지 옵션을 제공해요. Dialog 에 size 를 지정해요.

  • Medium (480px): 일반적인 데이터 입력 폼
  • Large (800px): 복잡한 설정, 대량의 데이터 조회

Height

Dialog는 콘텐츠 양에 따라 높이가 유동적으로 변하며, 가독성을 위해 최대 높이를 제한해요. 최대 높이(Max Height)는 화면 높이의 80%이며, 항상 화면의 정중앙에 배치돼요. 본문이 최대 높이를 넘으면 DialogBody 만 스크롤돼요.

Close Button

showCloseButton 으로 Header 오른쪽 위의 닫기 버튼을 표시할지 정해요. 기본값은 true 예요.

DialogFooter 안에서 버튼 배치를 자유롭게 구성할 수 있어요. 누르면 Dialog가 닫히는 버튼은 DialogAction 을 사용해요.

Controlled

Trigger 외의 방식으로 Dialog를 열고 닫으려면 open 과 onOpenChange 로 상태를 제어해요.

Guidelines

Elevation

Dialog는 시스템 내에서 가장 높은 시각적 위계를 가지며, 사용자의 즉각적인 집중을 요구해요.

  • 최상위 모달(Critical Modal): Dialog는 모든 UI 요소 중 가장 최상단에 위치해요. (Level 3)
  • 계층 구조: Level 2(Drawer, Bottom Sheet) 상위에서 동작하며, 활성화되면 하위 레벨의 모든 인터랙션을 일시 중단시켜요.

Scroll Behavior

  • Scroll Fog: 스크롤이 발생하면 Body 영역 하단에 Scroll Fog를 표시해요. Scroll Fog 높이만큼 하단 여백을 확보해 스크롤을 끝까지 내렸을 때 자연스럽게 표시되도록 해요.
  • Fixed Header & Footer: 본문 내용이 길어져도 제목(Header)과 버튼(Footer)은 항상 제자리에 고정돼요.
  • Body Scroll: 중앙의 Body 영역에만 세로 스크롤이 활성화돼요.
  • Divider Visibility: 본문이 스크롤되면 헤더 하단에 경계선(Divider)을 노출해 영역 구분을 명확히 해요.

Dialog의 닫기 동작

사용자가 작업을 중단하고 Dialog를 벗어나는 방법은 명확하고 일관되어야 해요.

  • Close Button (Header): 단순 정보 조회나 흐름 중단 시 사용해요. 마우스 사용자에게 가장 직관적인 탈출구예요.
  • Cancel Button (Footer): 입력 폼이나 설정 변경처럼 '확인/저장'이라는 주 작업이 있을 때, 이에 대응하는 명시적인 거절 의사로 사용해요.
  • Backdrop Click / ESC: 가장 빠른 종료 방식이며, 가벼운 알림이나 레이어에서 활용해요. Backdrop 클릭으로 닫으려면 closeOnInteractOutside 를 지정해요.

헤더의 닫기 버튼과 푸터의 취소 버튼을 동시에 제공하는 것은 지양해요. 단순 안내 및 조회를 위한 Dialog에서는 헤더의 닫기 버튼을, 데이터 입력이나 수정을 위한 Dialog에서는 푸터의 취소 버튼 사용을 권장해요.

닉네임 바꾸기
취소저장
Do· 입력 폼에는 취소 버튼

입력 폼이 있는 Dialog에서는 푸터 액션에 집중할 수 있도록 취소 버튼만 제공해요.

닉네임 바꾸기
✕
취소저장
Don't· 닫기와 취소를 함께

헤더의 닫기 버튼과 푸터의 취소 버튼을 동시에 제공하지 마세요.

Responsive Behavior

Dialog는 화면 크기에 맞춰 너비가 자동으로 조정돼요. 큰 화면에서는 Size 너비를 그대로 사용하고, 화면이 좁아지면 화면 너비의 90%로 표시돼요.

  • md 이상 (768px+): Size 너비 그대로 표시 (Medium = 480px, Large = 800px). 좌우에 최소 20px 여백을 둬요.
  • md 미만 (~767px): 화면 너비의 90%로 표시 (좌우 여백 5%씩 확보)
  • Scroll Behavior: 모든 환경에서 Body 스크롤 방식이 동일하게 적용돼요.

Responsive Dialog

데스크톱에서 Dialog를 사용하는 경우, md 미만 화면에서는 Bottom Sheet로 전환하는 것을 권장해요. Header/Body/Footer 구조는 두 컴포넌트에서 동일하게 유지해요.

  • md 이상 (768px+): Dialog로 표시
  • md 미만 (~767px): Bottom Sheet로 표시

Dialog vs Alert Dialog

Dialog와 Alert Dialog는 시각적으로 유사하지만, 사용 목적과 동작이 명확히 달라요. 콘텐츠의 성격과 사용자에게 요구되는 반응에 따라 선택해요.

Dialog는 작업 수행, 정보 조회, 폼 입력 등 사용자가 능동적으로 콘텐츠와 상호작용하는 경우에 사용해요. 사용자는 Dialog를 닫고 원래 작업으로 돌아갈 수 있으며, 시스템은 즉각적인 응답을 강제하지 않아요.

Alert Dialog는 시스템 메시지 전달, 사용자의 확인/경고가 필요한 경우에 사용해요. 사용자의 즉각적인 주의와 응답이 필요하며, 작업을 중단시키는 성격을 가져요.

구분DialogAlert Dialog
사용 목적작업 수행, 정보 조회, 폼 입력시스템 메시지 전달, 사용자 확인/경고
사용자 응답선택적 (닫고 원래 작업 복귀 가능)필수 (즉각적인 응답 요구)
Close ButtonHeader에 제공제공하지 않음
SizeMedium, Large단일 사이즈

Props

Dialog

Prop

Type

DialogContent

Prop

Type

DialogBody

본문 영역이에요. 넘치면 스크롤되고, 스크롤 상태에 따라 data-scrolled(상단 구분선), data-overflow(하단 Scroll Fog) 속성이 붙어요.

DialogAction

Action Button 의 모든 Props를 받아요. 누르면 Dialog가 닫히고, onClick 에서 event.preventDefault() 를 호출하면 닫히지 않아요.

Prop

Type

On this page