ComparisonsGitHubX

Dialog

<dialog />

A dialog is a modal surface that appears above the page to capture focused attention for a task, decision, or message. It dims or blocks the content behind it and returns the user to their prior context when dismissed.

The pattern is interruptive focus: use when the user must acknowledge, confirm, or complete something before continuing. Unlike inline panels, a dialog pauses the underlying workflow until it is closed.

Also known as

  • Modal
  • Modal dialog
  • Popup — informal
  • Lightbox — often image or media overlays; similar interaction model

Component Anatomy

PartRole
RootState container — open/closed, controlled or uncontrolled
TriggerControl that opens the dialog (button, link, menu item)
PortalRenders overlay and content outside the DOM hierarchy to avoid clipping
OverlayFull-screen backdrop — dims page content and signals modality
ContentCentered panel — title, body, and actions
HeaderGroups title and description at the top
TitlePrimary heading — names the dialog's purpose
DescriptionSupporting text — often muted, explains consequences or context
FooterBottom action row — confirm, cancel, secondary links
CloseDismiss control — icon button in the corner and/or explicit cancel action

Common use cases

Use a dialog when the user needs a short, focused interaction without leaving the current page:

  • Confirmations — delete account, discard unsaved changes, submit irreversible action
  • Quick forms — edit a single record, add a note, invite a teammate
  • Alerts — error summary, success acknowledgment, permission request
  • Detail on demand — expand an item for more context without full navigation
  • Media preview — enlarge an image or video in a lightbox-style overlay

Avoid a dialog when the content is long or multi-step (use a dedicated page or wizard), when users need to reference the page behind while working (use a side panel or inline expansion), or for non-blocking information (use a toast or inline banner). Do not stack dialogs on top of dialogs — combine steps or navigate to a full-page flow instead.

Modal dialogs block interaction with the page until dismissed. Non-modal dialogs are rare in web UI; prefer a popover or drawer when background interaction should remain available. Keep copy short; if the body scrolls extensively, the pattern has likely outgrown a dialog.

<Dialog />

Edit on GitHub