Course contentsShow
← Web Development
Lesson 1155 of 2,98221. Accessible ComponentsFree lesson

ARIA Attributes for Custom Dialogs

Using role='dialog', aria-modal, aria-labelledby, and aria-describedby for non-native implementations.

ARIA Attributes for Custom Dialogs

You'll learn how to properly mark up a custom dialog using ARIA attributes so screen readers understand its purpose and announce it correctly.

When you build a modal or dialog without the native <dialog> element (perhaps for broader browser support or framework constraints), you need to manually tell assistive technologies what your component is and how it behaves. This is where ARIA attributes become essential.

Core ARIA Attributes for Custom Dialogs

role="dialog"

This attribute identifies your container as a dialog to screen readers. Without it, a <div> is just a generic container. With role="dialog", assistive technologies announce it as a dialog and apply appropriate behavior.

<div role="dialog">
  <!-- dialog content -->
</div>

aria-modal="true"

This tells screen readers that the dialog is modal—meaning users should interact only with it while it's open. Content outside should be ignored. Think of it as a signal that the rest of the page is currently off-limits.

<div role="dialog" aria-modal="true">

aria-labelledby

This points to the ID of your dialog's title/heading, giving the dialog an accessible name. When the dialog opens, screen readers announce this title first, so users immediately know what the dialog is about.

<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
  <h2 id="dialog-title">Confirm Deletion</h2>
</div>

aria-describedby

This references additional descriptive text (like instructions or explanations) that provides context beyond the title. It's announced after the title.

<div role="dialog" aria-modal="true" 
     aria-labelledby="dialog-title"
     aria-describedby="dialog-desc">
  <h2 id="dialog-title">Confirm Deletion</h2>
  <p id="dialog-desc">This action cannot be undone.</p>
</div>

Key Takeaway: When building custom dialogs, use role="dialog", aria-modal="true", aria-labelledby (pointing to your title), and aria-describedby (pointing to descriptions) to create the same semantic clarity and screen reader experience as native dialogs.