# Modal dialog Pattern ID: modal-dialog Category: Disclosure And Attention Management Pattern type: UI + UX Surface type: Focused modal task layer Maturity: standard Platforms: web, mobile, desktop Last verified: 2026-06-08 Human page: https://uxpatternsguide.com/patterns/modal-dialog/ ## Agent Use Use this pattern contract when generating or reviewing UI. Choose it by user problem, task risk, required states, and interaction contract. Do not choose it only because the component name appears in the request. ## Problem Users sometimes need a short focused task layer that temporarily blocks the current page without sending them into a separate workflow. ## Solution 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. ## 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. ## 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. ## 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. ## 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. ## Failure Modes - Background remains interactive while the modal is visible. - Keyboard focus escapes behind the layer or disappears after close. - The dialog lacks a visible title or accessible name. - The task is too large for a temporary layer and becomes a cramped hidden page. - Action labels are vague, such as OK, and do not communicate the outcome. - Dialog content scrolls while actions become unreachable. - Multiple modal layers create unclear focus and close order. ## 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? ## 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. ## Quality Examples Good UI: - 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. Bad UI: - 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. Good UX: - 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. Bad UX: - 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. ## Related Patterns - [confirmation-dialog](https://uxpatternsguide.com/agent/patterns/confirmation-dialog.md) - [toast-only-critical-error](https://uxpatternsguide.com/agent/patterns/toast-only-critical-error.md) ## Comparisons - [Alert dialog vs alert vs modal dialog vs confirmation dialog](https://uxpatternsguide.com/agent/comparisons/alert-dialog-vs-alert-vs-modal-dialog-vs-confirmation-dialog.md) - [Drawer vs modal dialog vs navigation drawer vs filter panel](https://uxpatternsguide.com/agent/comparisons/drawer-vs-modal-dialog-vs-navigation-drawer-vs-filter-panel.md) - [Drawer with no close or return path vs drawer vs modal dialog vs navigation drawer vs details panel](https://uxpatternsguide.com/agent/comparisons/drawer-with-no-close-or-return-path-vs-drawer-vs-modal-dialog-vs-navigation-drawer-vs-details-panel.md) - [Focus traversal vs keyboard shortcut vs skip link vs modal dialog vs toolbar vs data grid](https://uxpatternsguide.com/agent/comparisons/focus-traversal-vs-keyboard-shortcut-vs-skip-link-vs-modal-dialog-vs-toolbar-vs-data-grid.md) - [Full-screen takeover vs modal dialog vs sheet vs single-page form](https://uxpatternsguide.com/agent/comparisons/full-screen-takeover-vs-modal-dialog-vs-sheet-vs-single-page-form.md) - [Inline edit vs text input vs single-page form vs modal dialog](https://uxpatternsguide.com/agent/comparisons/inline-edit-vs-text-input-vs-single-page-form-vs-modal-dialog.md) - [Modal dialog vs confirmation dialog](https://uxpatternsguide.com/agent/comparisons/modal-vs-confirmation-dialog.md) - [Modal for nonblocking content vs modal dialog vs popover vs drawer vs inline message](https://uxpatternsguide.com/agent/comparisons/modal-for-nonblocking-content-vs-modal-dialog-vs-popover-vs-drawer-vs-inline-message.md) - [Popover vs menu button vs modal dialog vs sheet](https://uxpatternsguide.com/agent/comparisons/popover-vs-menu-button-vs-modal-dialog-vs-sheet.md) - [Share dialog vs invite user vs object picker vs modal dialog](https://uxpatternsguide.com/agent/comparisons/share-dialog-vs-invite-user-vs-object-picker-vs-modal-dialog.md) - [Sheet vs drawer vs modal dialog vs alert dialog](https://uxpatternsguide.com/agent/comparisons/sheet-vs-drawer-vs-modal-dialog-vs-alert-dialog.md) ## Sources - [WAI-ARIA APG: Dialog Modal Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/): Defines modal dialog modality, inert background content, contained tab sequence, Escape dismissal, focus placement, and focus return. Checked 2026-06-08. - [W3C WCAG Technique H102: Creating modal dialogs with the HTML dialog element](https://www.w3.org/WAI/WCAG22/Techniques/html/H102.html): Documents HTML modal dialog checks including Escape dismissal and focus returning to the invoking element. Checked 2026-06-08. - [Atlassian Design System: Modal dialog](https://atlassian.design/components/modal-dialog): Frames modal dialogs as layered content requiring user interaction above the page. Checked 2026-06-08. - [Apple Human Interface Guidelines: Alerts](https://developer.apple.com/design/human-interface-guidelines/alerts): Helps distinguish interruptive alert-style decisions from ordinary focused modal tasks. Checked 2026-06-08.