# The “aria-describedby” attribute must point to an element in the same document.

> Canonical HTML version: https://rocketvalidator.com/html-validation/the-aria-describedby-attribute-must-point-to-an-element-in-the-same-document
> Attribution: Rocket Validator (https://rocketvalidator.com)
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

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:

```html
<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:

```html
<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`:

```html
<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:

```html
<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:

```html
<!-- "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:

```html
<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:

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