Aria Dialog Role

title: "ARIA Dialog Role — Creating Accessible Custom Modals" description: "Learn how to use role=dialog and role=alertdialog to create accessible custom modal dialogs with proper screen reader announcements." weight: 3 date: 2026-06-28 lastmod: 2026-06-28 tags: [accessibility, modals]

When the native dialog element is not suitable, use role="dialog" or role="alertdialog" to make custom modal containers accessible to screen readers.

## What You'll Learn

The difference between dialog and alertdialog roles, how to apply them, and the required ARIA attributes for each.

## Why It Matters

Custom modals made with divs have no semantic meaning. Adding role="dialog" tells screen readers that this element is a dialog window that requires specific interaction.

## Real-World Use

A complex modal with a form uses role="dialog" with aria-labelledby and aria-modal="true". The screen reader announces "Edit profile, dialog" and the user fills out the form inside.

## Dialog and Alertdialog

```html
<!-- Standard dialog -->
<div role="dialog" aria-labelledby="dialog-title"
     aria-describedby="dialog-desc" aria-modal="true">
  <h2 id="dialog-title">Edit profile</h2>
  <p id="dialog-desc">Update your profile information below.</p>
  <form>
    <label for="name">Name</label>
    <input type="text" id="name">
    <button type="submit">Save</button>
    <button type="button" onclick="closeDialog()">Cancel</button>
  </form>
</div>

<!-- Alert dialog for urgent confirmations -->
<div role="alertdialog" aria-labelledby="alert-title"
     aria-describedby="alert-message" aria-modal="true">
  <h2 id="alert-title">Unsaved changes</h2>
  <p id="alert-message">You have unsaved changes. Leave anyway?</p>
  <button onclick="leave()">Leave</button>
  <button onclick="stay()">Stay</button>
</div>

dialog vs alertdialog

Use role="dialog" for most cases. Use role="alertdialog" when:

• The dialog requires immediate user response
• The dialog contains a critical warning or error
• Screen readers should announce it immediately

Common Mistakes

1. Missing role="dialog" on custom modals

Without the role, screen readers treat the modal as regular page content.

2. Using alertdialog for non-critical content

alertdialog interrupts the user. Use it only for urgent confirmations.

3. No aria-labelledby on the dialog

The dialog needs an accessible name. Use aria-labelledby to reference the heading.

4. No aria-describedby for additional context

Use aria-describedby for the message or description text.

5. Forgetting aria-modal="true"

aria-modal indicates that content outside the dialog is not available for interaction.

Practice Questions

1. What is the difference between dialog and alertdialog? alertdialog is for urgent, time-sensitive confirmations. dialog is for standard modal interactions.

2. What ARIA attribute should a dialog have to reference its heading? aria-labelledby referencing the id of the heading element.

3. What does aria-modal="true" tell screen readers? It tells screen readers that content outside the modal is not available for interaction.

Challenge: Build a custom modal using a div with role="dialog", proper ARIA attributes, and keyboard support.

FAQ

Mini Project

Create a custom modal component using a div with role=dialog. Add aria-labelledby, aria-describedby, and aria-modal. Include a form inside the modal.

What's Next

Learn how ARIA Modal and the aria-modal attribute control screen reader behavior for modal content.