Using the alertdialog role
Description
This technique demonstrates how to use the alertdialog
role.
The alertdialog
role is used to notify the user of urgent information that demands the user's immediate attention. As the name implies, alertdialog
is a type of dialog. This means that most of the instructions provided in the 'using the dialog
role' technique are applicable to the alertdialog
role as well:
- The alert dialog must always be given an accessible name (through
aria-labelledby
oraria-label
) , and in most cases the alert text will have to be marked up as the alert dialog's accessible description (usingaria-describedby
). - Unlike regular alerts, an alert dialog must have at least one focusable control and focus must be moved to that control when the alert dialog appears. Generally alert dialogs have at least a Confirmation, Close or Cancel button that can be used to move focus to. Additionally, alert dialogs can have other interactive controls such as text fields, tabs or checkboxes. Which particular control focus should be moved to depends on the purpose of the dialog.
- The tab order inside the alert dialog must wrap.
The difference with regular dialogs is that the alertdialog
role should only be used when an alert, error, or warning occurs. In other words, when a dialog's information and controls require the user's immediate attention alertdialog
should be used instead of dialog
. It is up to the developer to make this distinction though.
Because of its urgent nature, alert dialogs must always be modal.
Note: This role should only be used for alert messages that have associated interactive controls. If an alert dialog only contains static content and has no interactive controls at all, alertdialog
is likely not the right role to use here. The alert
role should be used instead in that case (as the described in the Using the alert
role technique).
Possible effects on user agents and assistive technology
When the alertdialog
role is used, the user agent should do the following:
- Expose the element as a dialog in the operating system's accessibility API.
- Fire an accessible alert event using the operating system's accessibility API if it supports it.
When the alert dialog appears, screen readers should announce the alert.
When the alert 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 basic alert dialog
The code snippet below shows how to mark up an alert dialog that only provides a message and an OK button.
<div role="alertdialog" aria-labelledby="dialog1Title" aria-describedby="dialog1Desc">
<div role="document" tabindex="0">
<h2 id="dialog1Title">Your login session is about to expire</h2>
<p id="dialog1Desc">To extend your session, click the OK button</p>
<button>OK</button>
</div>
</div>
Working Examples:
TBD
Notes
ARIA attributes used
Related ARIA techniques
Compatibility
TBD: Add support information for common UA and AT product combinations