The dialog
role is used to mark up an HTML based application dialog or window that separates content or UI from the rest of the web application or page. Dialogs are generally placed on top of the rest of the page content using an overlay. Dialogs can be either non-modal (it's still possible to interact with content outside of the dialog) or modal (only the content in the dialog can be interacted with).
<div role="dialog" aria-labelledby="dialog1Title" aria-describedby="dialog1Desc"> <h2 id="dialog1Title">Your personal details were successfully updated</h2> <p id="dialog1Desc">You can change your details at any time in the user account section.</p> <button>Close</button> </div>
Description
Marking up a dialog element with the dialog
role helps assistive technology identify the dialog's content as being grouped and separated from the rest of the page content. However, adding role="dialog"
alone is not sufficient to make a dialog accessible. Additionally, the following needs to be done:
- The dialog must be properly labeled
- Keyboard focus must be managed correctly
The sections below describe how these two requirements can be met.
Labeling
Even though it is not required for the dialog itself to be able to receive focus, it still needs to be labeled. The label given to the dialog will provide contextual information for the interactive controls inside the dialog. In other words, the dialog's label acts like a grouping label for the controls inside it (similar to how a <legend>
element provides a grouping label for the controls inside a <fieldset>
element).
If a dialog already has a visible title bar, the text inside that bar can be used to label the dialog itself. The best way to achieve this is by using the aria-labelledby
attribute to the role="dialog"
element. Additionally, if the dialog contains additional descriptive text besides the dialog title, this text can be associated with the dialog using the aria-describedby
attribute. This approach is shown in the code snippet below:
<div role="dialog" aria-labelledby="dialog1Title" aria-describedby="dialog1Desc"> <h2 id="dialog1Title">Your personal details were successfully updated</h2> <p id="dialog1Desc">You can change your details at any time in the user account section.</p> <button>Close</button> </div>
Required JavaScript features
Focus management
A dialog has particular requirements for how keyboard focus should be managed:
- Dialogs should always have at least one focusable control. For many dialogs, there will be a button like "Close", "OK" or "Cancel". In addition to the needed control, dialogs can contain any number of focusable elements, even entire forms or other container widgets like tabs.
- When the dialog appears on the screen, keyboard focus (whose control depends upon the dialogs purpose) should be moved to the default focusable control inside the dialog. For dialogs that only provide a basic message, it could be an "OK" button. For dialogs containing a form it could be the first field in the form.
- After the dialog is dismissed, keyboard focus should be moved back to where it was before it moved into the dialog. Otherwise the focus can be dropped to the beginning of the page.
- For most dialogs, the expected behavior is that the dialog's tab order wraps, which means that when the user tabs through the focusable elements in the dialog, the first focusable element will be focused after the last one has been reached. In other words, the tab order should be contained within and by the dialog.
- If the dialog can be moved or resized, ensure that these actions must be performable by keyboard users as well as mouse users. Similarly, if a dialog provides special features like toolbars or context menus, these must be reachable and operable by keyboard users as well.
- Dialogs can be modal or non-modal. When a modal dialog appears on the screen, it's not possible to interact with any page content outside the dialog. In other words, the main application UI or page content is considered to be temporarily disabled as long as the modal dialog is showing. For non-modal dialogs it is still possible to interact with content outside of the dialog while the dialog is showing. Note that for non-modal dialogs there will have to be a global keyboard shortcut that allows focus to be moved between opened dialogs and the main page. For more information see the Managing Modal and Non Modal Dialogs guide.
Associated ARIA roles, states, and properties
aria-labelledby
- Use this attribute to label the dialog. Often, the value of the aria-labelledby attribute will be the id of the element used to title the dialog.
aria-describedby
- Use this attribute to describe the contents of the dialog.
Possible effects on user agents and assistive technology
When the dialog
role is used, the user agent should do the following:
- Expose the element as a dialog in the operating system's accessibility API.
When the dialog is correctly labeled and focus is moved to an element (often an interactive element, such as a button) inside the dialog, screen readers should announce the dialog's accessible role, name and optionally description, along with announcing the focused element.
Examples
A dialog containing a form
<div role="dialog" aria-labelledby="dialog1Title" aria-describedby="dialog1Desc"> <h2 id="dialog1Title">Subscription Form</h2> <p id="dialog1Desc">We will not share this information with third parties.</p> <form> <p> <label for="firstName">First Name</label> <input id="firstName" type="text" /> </p> <p> <label for="lastName">Last Name</label> <input id="lastName" type="text"/> </p> <p> <label for="interests">Interests</label> <textarea id="interests"></textarea> </p> <p> <input type="checkbox" id="autoLogin"/> <label for="autoLogin">Auto-login?</label> </p> <p> <input type="submit" value="Save Information"/> </p> </form> </div>
Working Examples:
Notes
Specifications
Specification | Status |
---|---|
Accessible Rich Internet Applications (WAI-ARIA) 1.1 The definition of 'alert' in that specification. |
Recommendation |
Screen reader support
Coming soon