aria-describedby

What Is aria-describedby?

aria-describedby is a WAI-ARIA attribute that creates a relationship between an element and one or more other elements that contain descriptive text. Unlike aria-label, which sets the accessible name, aria-describedby provides supplementary information that helps users understand context, requirements, or additional details about the element.

When a screen reader encounters an element with aria-describedby, it first announces the element's name and role, then after a brief pause, announces the content of the referenced description elements. This two-tier announcement gives users the essential information immediately and additional context right after.

The attribute works by referencing the id attribute of the describing element. Multiple descriptions can be referenced using a space-separated list of IDs, and their content will be concatenated in order.

Why It Matters

Many interface elements need more context than a simple name can provide. A password input labeled "Password" is clear enough, but users also need to know the requirements: minimum length, required character types, and other constraints. A delete button needs the user to understand what they are about to delete and that the action is permanent.

aria-describedby bridges this gap by associating supplementary instructions, warnings, error messages, or contextual information with the relevant interface element. Without it, screen reader users must hunt through surrounding content to find these details, assuming they realize the details exist at all.

WCAG Success Criterion 3.3.2 (Labels or Instructions) requires that labels or instructions are provided when content requires user input. While labels handle the "what" question, aria-describedby often handles the "how" by connecting instructions to the fields they apply to. Criterion 1.3.1 (Info and Relationships) requires that information and relationships conveyed visually are also available programmatically, which aria-describedby directly supports.

How It Works

The basic pattern connects an element to a description using id references:

<label for="email">Email Address</label>
<input type="email" id="email" aria-describedby="email-hint">
<p id="email-hint">We'll never share your email with third parties.</p>

In this example, a screen reader announces: "Email Address, edit text. We'll never share your email with third parties."

Multiple descriptions can be combined:

<label for="password">Password</label>
<input type="password" id="password" aria-describedby="pw-req pw-error">
<p id="pw-req">Must be at least 8 characters with one number.</p>
<p id="pw-error" class="error">Password is too short.</p>

The screen reader reads both descriptions in order, giving the user requirements and the current error state.

Common use cases include:

• Form field instructions. Help text, format requirements, and character limits associated with input fields.
• Error messages. Validation errors linked to the field that caused them, so users hear the error when they navigate to the problematic field.
• Tooltips and additional context. Supplementary information that appears on hover or focus.
• Confirmation dialogs. Descriptive text explaining the consequences of an action, linked to the action button.
• Group descriptions. Additional context for a group of related controls.

Important technical details:

The referenced elements can be visually hidden using CSS and the description will still be read by screen readers. This is useful when descriptive text would clutter the visual interface. However, if the referenced element has aria-hidden="true", the description will not be read.

<!-- Visually hidden description still works -->
<button aria-describedby="delete-desc">Delete</button>
<p id="delete-desc" class="visually-hidden">
  This will permanently delete the file and cannot be undone.
</p>

aria-describedby differs from aria-details, which was introduced in ARIA 1.2. While aria-describedby expects a flat text description that screen readers can read aloud, aria-details references structured content like tables or lists that users may want to navigate into.

Be mindful that not all screen readers handle aria-describedby identically. Some announce descriptions automatically, while others require users to request additional information with a keyboard shortcut. Testing across multiple screen readers ensures your implementation works broadly.