Dialog Aria Labelledby Describedby

title: "Dialog ARIA Labelledby and Describedby — Naming and Describing Dialogs" description: "Learn how to use aria-labelledby and aria-describedby to give modals proper accessible names and descriptions for screen reader announcements." weight: 11 date: 2026-06-28 lastmod: 2026-06-28 tags: [accessibility, modals]

aria-labelledby and aria-describedby give modals an accessible name (heading) and description (message) so screen readers announce the dialog purpose and content.

## What You'll Learn

How to use aria-labelledby for the dialog title and aria-describedby for the description, following the ARIA dialog pattern.

## Why It Matters

Without an accessible name, a modal is announced as "dialog" with no context. Users must explore the content to understand its purpose.

## Real-World Use

A screen reader opens a modal and hears "Confirm deletion, dialog, Are you sure? This cannot be undone." The aria-labelledby provides the title, aria-describedby provides the description.

## Dialog Labelling

```html
<div role="dialog" aria-labelledby="dialog-title"
     aria-describedby="dialog-desc">
  <h2 id="dialog-title">Delete account</h2>
  <p id="dialog-desc">This action is permanent and cannot be undone.</p>
  <button onclick="confirm()">Confirm</button>
  <button onclick="close()">Cancel</button>
</div>

Multiple References

<div role="dialog"
     aria-labelledby="dialog-title dialog-subtitle"
     aria-describedby="dialog-desc dialog-warning">
  <h2 id="dialog-title">Export data</h2>
  <p id="dialog-subtitle">Select your export preferences</p>
  <p id="dialog-desc">Your data will be sent to your email as a CSV file.</p>
  <p id="dialog-warning" role="alert">This may take up to 24 hours.</p>
</div>

Dynamic Description

function updateDialogDescription(text) {
  const desc = document.getElementById('dialog-desc');
  desc.textContent = text;
  // Update aria-describedby reference
  dialog.setAttribute('aria-describedby', 'dialog-desc');
}

Common Mistakes

1. Using aria-label instead of aria-labelledby

aria-label works but aria-labelledby is preferred when a visible heading exists.

2. Pointing to non-unique ids

Each id referenced must be unique on the page. Duplicate ids break the association.

3. No id on the heading

aria-labelledby references an id. The heading must have an id attribute.

4. aria-describedby on the wrong element

Put aria-describedby on the dialog element, not on the heading or buttons.

5. Description too long

Keep descriptions concise. Long descriptions are truncated or skipped by screen readers.

Practice Questions

1. What attribute gives a dialog its accessible name? aria-labelledby referencing the heading element's id gives the dialog its accessible name.

2. What attribute provides additional context about dialog content? aria-describedby provides a description of the dialog's purpose or content.

3. Can a dialog have both aria-labelledby and aria-describedby? Yes. aria-labelledby provides the name. aria-describedby provides supplementary description.

Challenge: Build a modal with a title, a subtitle, a description, and a warning. Use multiple aria-labelledby and aria-describedby references.

FAQ

Mini Project

Create three dialogs: a simple confirmation, a form dialog, and an error dialog. Each must have proper aria-labelledby and aria-describedby. Test screen reader announcements.

What's Next

Apply everything in the Modal Project by building a complete accessible modal system.