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 or aria-label) , and in most cases the alert text will have to be marked up as the alert dialog's accessible description (using aria-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

Compatibility

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

Additional resources