Using the dialog role

The dialog role is used to mark up a DHTML based application dialog or window that separates content or UI from the rest of the web application or page. Visually, 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).

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>

Keep in mind that a dialog's title and description text do not have to be focusable in order to be perceived by screen readers operating in a non-virtual mode. The combination of the ARIA dialog role and labeling techniques should make the screen reader announce the dialog's information when focus is moved into it.

Focus management

A dialog has particular requirements for how keyboard focus should be managed:

Dialogs always need to have at least one focusable control. For many dialogs, there will be a button like "Close", "OK" or "Cancel". Besides that, 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 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.

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 a control inside the dialog, screen readers should announce the dialog's accessible role, name and optionally description before announcing the focused element.

Note: Opinions may differ on how assistive technology should handle this technique. The information provided above is one of those opinions and therefore not normative.

Examples

Example 1: 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">Interests</label>
     </p>
     <p>
         <input type="submit" value="Save Information"/>
     </p>
   </form>
 </div>

Example 2: A dialog based on a Fieldset as fallback content

To support browsers or AT products that do not support ARIA mark up, it's also possible to use apply the dialog markup to a fieldset element as fallback content. This way the dialog title will still be announced correctly:

<fieldset role="dialog" aria-labelledby="dialog1Title" aria-describedby="dialog1Desc">
  <legend>
    <span id="dialog1Title">Your personal details were successfully updated.</span>
    <span id="dialog1Desc">You can change your details at any time in the user account section.</span>
  </legend>
  <button>Close</button>
</fieldset>

Working Examples:

jQuery-UI Dialog

Notes

Note: While it is possible to prevent keyboard users from moving focus to elements outside of the dialog. Screen reader users may still be able to navigate that content virtually to use their screen reader's virtual cursor. Because of this, dialogs are considered to be a special case of the application role: They are expected to be navigated by screen reader users in a non-virtual navigation mode.

Labeling

Focus management

Possible effects on user agents and assistive technology

Examples

Example 1: A dialog containing a form

Example 2: A dialog based on a Fieldset as fallback content

Working Examples:

Notes

ARIA attributes used

Related ARIA techniques

Compatibility

Additional resources

Document Tags and Contributors