UX Patterns Guide
UI + UX Disclosure And Attention Management standard

Modal dialog

Open a titled dialog above the current page, make background content unavailable, place focus inside the dialog, keep focus contained until close, then return focus to the invoking control or next logical workflow point.

Open in lab Compare alternatives
Decision first

Choose this pattern when the problem matches

Use when

  • A short task must interrupt normal page interaction but should return users to the same context afterward.
  • The background page should remain visible for orientation but unavailable for interaction.
  • The task has clear complete and cancel outcomes.

Avoid when

  • The content is only informational and does not require blocking the page.
  • The workflow is long, multi-step, shareable, or needs browser navigation.
  • Users must inspect or manipulate background content while the layer is open.
  • The only purpose is to confirm a destructive action, which needs confirmation-dialog guidance.
  • Focus containment and background inactivation cannot be implemented reliably.

Problem it prevents

Users sometimes need a short focused task layer that temporarily blocks the current page without sending them into a separate workflow.

Pattern anatomy

What a strong implementation has to make clear

User need

The user is working in a larger page but must complete a compact task before continuing.

Pattern promise

Open a titled dialog above the current page, make background content unavailable, place focus inside the dialog, keep focus contained until close, then return focus to the invoking control or next logical workflow point.

Required state

Closed page state with an obvious invoking control.

Recovery path

Background remains interactive while the modal is visible.

Access contract

Use dialog semantics with an accessible name from the visible title.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • Account settings opens in a titled dialog with one display-name field, Save, Cancel, close control, and dimmed inactive page context.
  • The dialog panel has a clear accessible name, stable width, readable body copy, and actions that remain visible.
  • Opening moves focus to the display-name field, Tab remains inside the layer, Escape cancels, and closing returns focus to Open dialog.
  • Save applies the compact task and returns the user to the same page context with a clear status message.
Weak implementation

Vague, hidden, hard to recover from

  • A vague popup titled Popup floats over active page controls and offers only OK.
  • A long settings workflow is squeezed into a small modal where the primary action scrolls out of reach.
  • Users can click background Delete or Navigate controls while the modal is still open.
  • Closing the dialog drops focus at the top of the document or loses the user's previous context.
UI guidance
  • Render a titled layer above a dimmed or otherwise unavailable page, with clear task content, named actions, visible close or cancel affordance, and stable scroll boundaries.
  • Keep background controls visually present for orientation but unavailable to pointer and keyboard interaction while the modal is open.
UX guidance
  • Use the modal interruption only for compact tasks that genuinely need temporary focus before the user returns to the page.
  • Make entry, completion, cancellation, Escape dismissal, and focus return predictable so users understand they are in a temporary mode.
Implementation contract

What the implementation must handle

States

  • Closed page state with an obvious invoking control.
  • Opening transition that moves focus into the dialog and marks background content unavailable.
  • Open task state with accessible title, concise body, primary action, secondary cancellation, and visible close behavior.
  • Keyboard cycling state where Tab and Shift+Tab remain inside the dialog.

Interaction

  • Opening the modal moves focus to the best starting element inside the dialog, not to the dimmed page.
  • Tab and Shift+Tab cycle through focusable elements in the dialog until the user closes it.
  • Escape closes dismissible modal tasks and follows the same cleanup path as cancel.
  • Background controls cannot be clicked, focused, or changed while the modal is active.

Accessibility

  • Use dialog semantics with an accessible name from the visible title.
  • Indicate modality so assistive technologies know the background is unavailable.
  • Move focus into the dialog on open.
  • Keep keyboard focus inside the dialog while it is modal.

Review

  • What page interaction must be blocked while this task is open?
  • Can the task be completed in one focused layer without navigation or saved progress?
  • Where exactly does focus go on open, on Tab wrap, on Escape, on cancel, and on completion?
  • Would a drawer, inline panel, or full page preserve the user's context better than a modal?
Interactive lab

Inspect the states before you copy the pattern

Complete a focused modal task

Open the dialog, test Tab and Escape, then verify focus returns to the opener.

Modal dialog
Interactive demo is ready

Launch the live UI/UX lab when you want to inspect states, keyboard behavior, and common failure modes.

State To Inspect

Closed page state with an obvious invoking control.

Keyboard / Access

Enter or Space on the invoking control opens the modal.

Avoid Generating

Using a modal as a generic container for routine information that could stay inline.
Evidence trail

Source-backed claims behind this guidance

WAI-ARIA APG: Dialog Modal Pattern

W3C Web Accessibility Initiative - checked

Defines modal dialog modality, inert background content, contained tab sequence, Escape dismissal, focus placement, and focus return.

Full agent/debug reference

Problem Context

  • The user is working in a larger page but must complete a compact task before continuing.
  • The task benefits from preserving page context while preventing accidental interaction behind the layer.
  • The content can be completed, cancelled, or dismissed without requiring navigation history or a long-lived workspace.
  • The product can manage focus, close behavior, and background inactivation reliably.

Selection Rules

  • Choose a modal dialog for a short contained task that must temporarily suspend interaction with the page behind it.
  • Use a full page when the task needs multiple steps, complex reading, saved progress, deep links, or durable browser history.
  • Use inline disclosure, a popover, or a drawer when users must continue comparing or editing background content while the layer is visible.
  • Use a confirmation dialog only when the dialog's main job is protecting a consequential action.
  • Use nonblocking feedback such as a banner, toast, or inline message when users only need status information.
  • Avoid nested modal stacks unless the second layer is unavoidable and focus return can still be made predictable.

Required States

  • Closed page state with an obvious invoking control.
  • Opening transition that moves focus into the dialog and marks background content unavailable.
  • Open task state with accessible title, concise body, primary action, secondary cancellation, and visible close behavior.
  • Keyboard cycling state where Tab and Shift+Tab remain inside the dialog.
  • Dismissed state that restores focus to the invoker and leaves the page unchanged.
  • Completed state that applies the task, closes the layer, and returns focus to a logical point.
  • Overflow state for dialog content that scrolls inside the layer without losing access to actions.

Interaction Contract

  • Opening the modal moves focus to the best starting element inside the dialog, not to the dimmed page.
  • Tab and Shift+Tab cycle through focusable elements in the dialog until the user closes it.
  • Escape closes dismissible modal tasks and follows the same cleanup path as cancel.
  • Background controls cannot be clicked, focused, or changed while the modal is active.
  • Closing through save, cancel, Escape, or close button restores focus to the opener unless the workflow clearly moves elsewhere.
  • The dialog has an accessible name from its visible title and a useful description when body copy explains the task.
  • Primary and secondary actions describe the task outcome rather than using vague OK-only controls.

Implementation Checklist

  • Give the dialog a visible title and wire it to the dialog's accessible name.
  • Keep the task compact enough that users can complete it without page navigation.
  • Make the rest of the page inert or otherwise unavailable while the modal is open.
  • Move focus into the dialog on open and restore focus after every close path.
  • Implement contained Tab and Shift+Tab movement for keyboard users.
  • Support Escape for dismissible tasks and provide an explicit cancel or close affordance.
  • Keep critical actions visible when dialog content scrolls.
  • Prevent nested modal chains in ordinary workflows.
  • Test pointer, keyboard, screen reader, reduced viewport, and long-content behavior.

Common Generated-UI Mistakes

  • Using a modal as a generic container for routine information that could stay inline.
  • Letting users interact with page controls behind the open dialog.
  • Opening a long multi-step workflow in a modal without navigation, progress, or saved state.
  • Providing only an OK button for a task that can be cancelled or needs a named action.
  • Moving focus into the dialog on open but failing to return it on close.
  • Stacking modal dialogs until users cannot understand where they are.

Critique Questions

  • What page interaction must be blocked while this task is open?
  • Can the task be completed in one focused layer without navigation or saved progress?
  • Where exactly does focus go on open, on Tab wrap, on Escape, on cancel, and on completion?
  • Would a drawer, inline panel, or full page preserve the user's context better than a modal?
  • Does the title name the task rather than merely saying dialog or popup?
Accessibility
  • Use dialog semantics with an accessible name from the visible title.
  • Indicate modality so assistive technologies know the background is unavailable.
  • Move focus into the dialog on open.
  • Keep keyboard focus inside the dialog while it is modal.
  • Return focus to the invoking control or next logical element when closing.
  • Provide Escape and an explicit cancel or close path for dismissible tasks.
  • Avoid describing large semantic content as one unbroken accessible description.
Keyboard Behavior
  • Enter or Space on the invoking control opens the modal.
  • Initial focus lands on the best task starting point, often the first field or a static heading for long content.
  • Tab moves to the next focusable dialog element and wraps from the last item to the first.
  • Shift+Tab moves backward and wraps from the first item to the last.
  • Escape closes dismissible modal tasks without activating the primary action.
  • After save, cancel, close, or Escape, focus returns to the opener unless workflow order requires another target.
Variants
  • Form dialog
  • Picker dialog
  • Settings dialog
  • Short task modal
  • Full-screen modal on small viewports
  • Alert dialog
  • Confirmation dialog

Verification

Last verified: