aria-describedby — Adding Descriptions to Elements for Screen Readers

In this tutorial, you will learn about aria. We cover key concepts, practical examples, and best practices to help you master this topic.

aria-describedby provides additional descriptive text for an element, supplementing the accessible name with instructions, hints, or error details from referenced elements.

In this tutorial, you'll learn how to use aria-describedby to add helpful descriptions to elements in your ARIA implementations.

What You'll Learn

By the end of this lesson, you'll understand the difference between labels and descriptions, know when to use aria-describedby, how to reference multiple description elements, and how to test the results.

Why It Matters

Labels identify what an element is. Descriptions provide additional context. A password field might have the label "Password" and the description "Must be at least 8 characters with one number."

Real-World Use

Durga Antivirus Pro's form fields use aria-describedby to link validation error messages, ensuring screen reader users hear the error after the field label.

Label vs Description

flowchart LR
  A[Element Communication] --> B[Label: What is this?]
  A --> C[Description: How to use it?]
  B --> D[aria-label or aria-labelledby]
  C --> E[aria-describedby]
  D --> F[Short, essential]
  E --> G[Longer, supplemental]

How aria-describedby Works

aria-describedby references one or more element IDs containing descriptive text. Screen readers announce the description after the label and role:

<label for="email">Email address</label>
<input type="email" id="email" aria-describedby="email-hint" />
<p id="email-hint">We will never share your email. Enter a valid email format.</p>

The screen reader announces: "Email address, edit text. We will never share your email. Enter a valid email format."

Multiple Description Sources

You can reference multiple elements to compose a description:

<label for="password">Password</label>
<input type="password" id="password" aria-describedby="password-rules password-strength" />
<p id="password-rules">8+ characters with a number and symbol.</p>
<p id="password-strength" role="status">Strength: Strong</p>

Screen readers announce both descriptions in ID order.

aria-describedby vs aria-labelledby

<button aria-describedby="button-desc">Save</button>
<p id="button-desc">Saves your settings and exits the panel.</p>

The screen reader announces: "Save button. Saves your settings and exits the panel."

Common Mistakes

• Using aria-describedby for the element name: Use aria-label or aria-labelledby for names.
• Referencing too many elements: Long concatenated descriptions are hard to understand.
• Using aria-describedby on non-interactive elements: Description is most useful for interactive elements.
• Not testing with a screen reader: Descriptions that look correct in code may not announce as expected.
• Using the same content for label and description: Redundant information wastes the user's time.

Practice and Challenge

1. What is aria-describedby used for? Providing additional descriptive text beyond the accessible name.

2. How is a description announced compared to a label? The label is announced first, then the role and state, then the description.

3. Can aria-describedby reference multiple elements? Yes, with a space-separated list of IDs.

4. What is the main use case for aria-describedby? Linking form field instructions or error messages to form controls.

5. Challenge: Create a form with three fields. Add aria-describedby to each field linking to its hint text. Test with a screen reader.

FAQ

Mini Project

Add aria-describedby to a checkout form. Link each field to its hint text, and link the submit button to a summary of items being purchased. Test with NVDA.

What's Next

Continue to aria-hidden to learn how to hide content from assistive technology.