Dialog (modal)

Definition

A Dialog, also known as a Modal, is a window overlaid on either the primary window or another Dialog. Typically, content under a Dialog window cannot be interacted with and styling is applied to visually indicate this like dimming or obscuring the content. Also, trying to interact with this content might cause the Dialog to close.

A common use case for a Dialog would be a window that appears asking the user if they are sure about executing a destructive action, such as deleting a comment on a social media post or deleting an account for a website.

Usage Guidelines

Once a Dialog is open, users should only be able to tab through the tabbable elements within the Dialog. So users may only move keyboard focus outside the Dialog by closing the Dialog. The element that closes the Dialog should be included in the tab sequence.

If a Dialog completes a task that is not easily reversible, focus should be set on the least-destructive action such as “Cancel.”. If a Dialog’s purpose is to provide additional information or continue processing a task, focus should be set on the element that is most likely to be frequently used such as “Continue”.

Focus Expectations

Focus should move to an element within the dialog after it opens, unless:
- Content is large enough that focusing the first interactive element scrolls the start of content out of view
- In this case, tabindex=-1 should be set on a static element at the top of the Dialog and focus set on that
Focus should return to the element that opened the dialog after it closes, unless either:
- The invoking element no longer exists and then, focus is set to the next logical element in the work flow
- It is more logical to set focus to a different element which could be because it is unlikely for users to reinvoke the Dialog, or the task completed in the Dialog is directly related to the next step in the work flow

Semantic Elements

button element (e.g. <button>)

ARIA Roles and Attributes

The element that contains the Dialog should have a role of dialog
The container element has aria-modal set to true only when both of the following are true:
- Application code prevents users from interacting with content outside the Dialog
- Visual styling obscures content outside of the Dialog
Optionally, the container element has aria-describedby set to indicate which element or elements describe the purpose or message of the Dialog
- Omit aria-describedby when the Dialog includes semantic structures that would be difficult to understand if announced as a single, unbroken string like lists or tables
- In cases that include semantic structure, tabindex=1 should be set on a static element before the semantic structure and focus set on that
The Dialog has either:
- An aria-labelledby value referring to a visible Dialog title
- An aria-label value specifying a label
All elements required to operate the Dialog are descendants of the container element
The element that closes the Dialog should be visible and have a role of button (such as a <button> element)

Keyboard Interactions