When a modal dialog or alert pops up on a webpage, it immediately becomes the focus. For a screen reader user, the first thing they need to know is, “What is this window for?” An accessible name provides that crucial piece of information. It’s the “title” that a screen reader announces when the dialog opens, giving the user immediate context. Without an accessible name, your dialogs can be a confusing and frustrating experience for users who are blind or have low vision.

Think of your ARIA dialogs as a person. You wouldn’t walk up to a stranger and start talking to them without first introducing yourself. The same is true for your dialogs. By giving your dialogs an accessible name, you’re introducing them to your users and telling them what they’re all about. For a deeper dive into the world of accessibility, see our article on accessibility.

An illustration of a name tag, symbolizing the importance of giving your ARIA dialogs an accessible name.

Two Ways to Name a Dialog

There are two primary methods for providing an accessible name to a dialog, as detailed in the MDN Web Docs for the dialog role. The method you choose depends on whether the dialog has a visible title.

  • aria-labelledby: This is the preferred method. You use it when your dialog has a visible title (e.g., in an `<h2>` tag). The attribute’s value should be the `id` of the element that contains the title.
  • aria-label: This method is used when your dialog does not have a visible title. The attribute’s value is a short, descriptive string that acts as the title for the screen reader.

Implementation Examples

Fixing a missing accessible name is a simple but important task. Here are “before and after” examples for both methods.

Using `aria-labelledby` (Preferred)

<!-- Before: No accessible name -->
<div role="dialog">
 <h2>Confirm Deletion</h2>
 <p>Are you sure you want to delete this item?</p>
</div>
<!-- After: Correctly named with aria-labelledby -->
<div role="dialog" aria-labelledby="dialog-title">
 <h2 id="dialog-title">Confirm Deletion</h2>
 <p>Are you sure you want to delete this item?</p>
</div>

Using `aria-label`

<!-- Before: No accessible name -->
<div role="dialog">
 <p>Your session is about to expire.</p>
</div>
<!-- After: Correctly named with aria-label -->
<div role="dialog" aria-label="Session Timeout Warning">
 <p>Your session is about to expire.</p>
</div>

For more on the importance of a well-structured website, check out this guide to ARIA dialogs from the W3C.

An illustration of two people having a conversation, symbolizing the importance of clear communication in web accessibility.

Frequently Asked Questions

What is an ARIA dialog?

An ARIA dialog is a type of modal window that is used to display important information to the user. It’s often used for things like login forms, confirmation messages, and error messages.

What is the difference between a ‘dialog’ and an ‘alertdialog’?

A `dialog` is a generic window that can contain any type of content. An `alertdialog` is a specific type of dialog that is used for urgent messages that require an immediate user response, like an error confirmation. An `alertdialog` must be modal and contain at least one focusable control (like ‘OK’ or ‘Cancel’).

How do I give my ARIA dialogs an accessible name?

You can give your ARIA dialogs an accessible name by using the ‘aria-labelledby’ or ‘aria-label’ attribute. The ‘aria-labelledby’ attribute should be used to point to the ID of the element that contains the dialog’s title. The ‘aria-label’ attribute should be used to provide a short, descriptive name for the dialog.