semantic pattern · Dialog and side surfaces

Dialog

A separate window layered over a page that contains a focused task or information and may be modal or non-modal.

reviewpublishedV1 field note

Decisive boundary

Do not assume every dialog is modal. State whether background interaction is blocked.

Definition and intent

What is a Dialog UI pattern?

Use the behavior, not the silhouette

A separate window layered over a page that contains a focused task or information and may be modal or non-modal. The term is used here as a semantic pattern whose role and interaction contract carry more meaning than its appearance. That distinction prevents a visual resemblance from silently deciding focus, keyboard, modality, or dismissal behavior.

Present a distinct task or information surface without navigating to another page. A good implementation preserves that job while making the trigger, open state, close path, and responsive behavior observable to users.

Know when the label is wrong

The fastest way to identify a pattern is often to reject the nearest alternative. For Dialog, the boundary is: Do not assume every dialog is modal. State whether background interaction is blocked.

Do not implement it as Modal Dialog unless background blocking is required, and Drawer when edge entry is the essential presentation. If those requirements describe the real task better, use the related pattern page or the full Dialog and side surfaces comparison before writing code.

Decision process

Decide before choosing a component

Record these requirements in plain language. A library component name is not a substitute for the contract.

Confirm the user job

Present a distinct task or information surface without navigating to another page.

Define opening and closing

An explicit user action or application event. Explicit close, completion, cancel, and optionally Escape.

Specify access behavior

Focus moves according to task needs and returns to a logical point on close. All controls are reachable; Escape behavior must be explicit.

Reject the near miss

Modal Dialog unless background blocking is required, and Drawer when edge entry is the essential presentation.

Behavior contract

What must survive the build

trigger: An explicit user action or application event.
dismissal: Explicit close, completion, cancel, and optionally Escape.
modality: May be modal or non-modal; this entry represents the general pattern.
focus: Focus moves according to task needs and returns to a logical point on close.
keyboard: All controls are reachable; Escape behavior must be explicit.
interactive: Supports a focused task or decision.
persistence: Remains until dismissed or the task completes.
placement: Layered over the primary document; not defined by edge entry.
mobile: May become full-screen when the task needs more space.

Failure modes

Common wrong builds

Using modal semantics without blocking the background.
Losing focus on close.
Calling any floating card a dialog.

Observable checks

Verify the result

The dialog has an accessible name.
Focus enters a useful location.
Close behavior is explicit.
Focus returns logically.
Modality matches actual background behavior.

Coding-agent handoff

Implementation brief template

Pattern: Dialog
Purpose: Present a distinct task or information surface without navigating to another page.
Trigger: An explicit user action or application event.
Dismissal behavior: Explicit close, completion, cancel, and optionally Escape.
Modality: May be modal or non-modal; this entry represents the general pattern.
Focus behavior: Focus moves according to task needs and returns to a logical point on close.
Keyboard behavior: All controls are reachable; Escape behavior must be explicit.
Interactive content: Supports a focused task or decision.
Placement: Layered over the primary document; not defined by edge entry.
Mobile behavior: May become full-screen when the task needs more space.
Do not implement as: Modal Dialog unless background blocking is required, and Drawer when edge entry is the essential presentation.
Acceptance checks:
- The dialog has an accessible name.
- Focus enters a useful location.
- Close behavior is explicit.
- Focus returns logically.
- Modality matches actual background behavior.

Claim-level references

Sources, not a confidence score

01The dialog elementMDN Web Docs · Platform documentation

Native modal and non-modal dialog behavior

Frequently asked questions

Dialog UI pattern questions

Direct answers based on the reviewed behavior contract above.

What is a Dialog in web UI?

A separate window layered over a page that contains a focused task or information and may be modal or non-modal. In this reference set it is a semantic pattern whose role and interaction contract carry more meaning than its appearance.

When should I use a Dialog?

Present a distinct task or information surface without navigating to another page. The decisive boundary to confirm is this: Do not assume every dialog is modal. State whether background interaction is blocked.

What keyboard and focus behavior does a Dialog need?

All controls are reachable; Escape behavior must be explicit. Focus moves according to task needs and returns to a logical point on close. These statements describe the reviewed expectation, but the final implementation still needs testing in the component library and browser you ship.

How should a Dialog behave on mobile?

May become full-screen when the task needs more space. Its modality is a separate requirement: May be modal or non-modal; this entry represents the general pattern.

How do I verify a Dialog implementation?

Start with observable checks: The dialog has an accessible name. Focus enters a useful location. Close behavior is explicit. Then verify the remaining checks and compare the result with the linked source guidance.