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>

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.
• 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. 

Examples

Example 1: A dialog containing a form

 <div role="dialog" aria-labelledby="dialog1Title" aria-describedby="dialog1Desc">
   <h2 id="dialog1Title">Subscribtion 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">First 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 

ARIA attributes used

• dialog
• aria-labelledby
• aria-describedby

Related ARIA techniques 

• Using the alertdialog role

Compatibility

TBD: Add support information for common UA and AT product combinations

Additional resources