HTML Guides for aria-describedby

An a element with both an href attribute and aria-disabled="true" is invalid; either remove aria-disabled or the href attribute.

The aria-disabled attribute is used for interactive elements to indicate that the element is perceivable as disabled by assistive technologies. However, using aria-disabled="true" in combination with an href attribute on an a element is not valid, because the link remains actionable for both user agents and assistive devices. Instead, if a link should appear disabled, you should remove the href attribute, use CSS for styling, and optionally use aria-disabled="true". If you need the element to always act as a link, avoid aria-disabled and control user access through application logic.

Incorrect:

<a href="page.html" aria-disabled="true">Visit Page</a>

Correct—Option 1: Remove aria-disabled, keep link active

<a href="page.html">Visit Page</a>

Correct—Option 2: Remove href, use aria-disabled, for non-actionable item

<a aria-disabled="true" tabindex="-1" style="pointer-events: none; color: gray;">Visit Page</a>

In the second correct example, setting tabindex="-1" prevents keyboard navigation, and pointer-events: none; makes the link unclickable, while aria-disabled="true" makes the disabled state accessible.

The aria-describedby attribute is a core part of WAI-ARIA, the Web Accessibility Initiative’s specification for making web content more accessible. It works by creating a relationship between an element and one or more other elements that provide additional descriptive text. Screen readers and other assistive technologies use this relationship to announce the descriptive text when a user interacts with the element.

When you set aria-describedby="some-id", the browser looks for an element with id="some-id" in the same document. If no matching element exists, the reference is broken. This means assistive technologies cannot find the description, and the attribute silently does nothing. The W3C validator flags this as an error because a dangling reference indicates a bug — either the referenced element was removed, renamed, or was never added.

This issue commonly arises due to:

• Typos in the id value — the aria-describedby value doesn’t match the target element’s id exactly (the match is case-sensitive).
• Dynamic content — the described-by element is rendered conditionally or injected by JavaScript after validation.
• Copy-paste errors — markup was copied from another page or component, but the referenced element wasn’t included.
• Refactoring — an element’s id was changed or the element was removed, but the aria-describedby reference wasn’t updated.

Multiple id values can be listed in aria-describedby, separated by spaces. Every single id in that list must resolve to an element in the document. If even one is missing, the validator will report an error for that reference.

How to fix it

1. Check for typos. Compare the value in aria-describedby against the id of the target element. Remember that id matching is case-sensitive — helpText and helptext are different.
2. Add the missing element. If the descriptive element doesn’t exist yet, create it with the matching id.
3. Remove stale references. If the description is no longer needed, remove the aria-describedby attribute entirely rather than leaving a broken reference.
4. Verify all IDs in a multi-value list. If aria-describedby contains multiple space-separated IDs, confirm each one exists.

Examples

Broken reference (triggers the error)

In this example, aria-describedby points to password-help, but no element with that id exists in the document:

<label for="password">Password</label>
<input type="password" id="password" aria-describedby="password-help">

Fixed by adding the referenced element

Adding an element with id="password-help" resolves the issue:

<label for="password">Password</label>
<input type="password" id="password" aria-describedby="password-help">
<p id="password-help">Must be at least 8 characters with one number.</p>

Broken reference due to a typo

Here the aria-describedby value uses a different case than the element’s id:

<input type="text" id="email" aria-describedby="emailHelp">
<small id="emailhelp">We'll never share your email.</small>

The fix is to make the id values match exactly:

<input type="text" id="email" aria-describedby="email-help">
<small id="email-help">We'll never share your email.</small>

Multiple IDs with one missing

When listing multiple descriptions, every id must be present:

<!-- "format-hint" exists but "length-hint" does not — this triggers the error -->

<input type="text" id="username" aria-describedby="format-hint length-hint">
<span id="format-hint">Letters and numbers only.</span>

Fix it by adding the missing element:

<input type="text" id="username" aria-describedby="format-hint length-hint">
<span id="format-hint">Letters and numbers only.</span>
<span id="length-hint">Between 3 and 20 characters.</span>

Removing the attribute when no description is needed

If the descriptive content has been removed and is no longer relevant, simply remove the aria-describedby attribute:

<input type="text" id="search">