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

> Canonical HTML version: https://rocketvalidator.com/html-validation/the-aria-labelledby-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-labelledby` attribute creates a relationship between an element and the text content that labels it. It works by pointing to the `id` of one or more elements whose text should be used as the accessible name. When the validator reports that `aria-labelledby` must point to an element in the same document, it means at least one of the `id` values you referenced doesn't correspond to any element on the page.

This typically happens for a few reasons:

- **Typo in the `id`** — the `aria-labelledby` value doesn't exactly match the target element's `id` (remember, IDs are case-sensitive).
- **The referenced element was removed** — the labeling element existed at some point but was deleted or moved, and the reference wasn't updated.
- **The `id` exists in a different document** — `aria-labelledby` cannot reference elements across pages, iframes, or shadow DOM boundaries. The target must be in the same document.
- **Dynamic content not yet rendered** — the element is inserted by JavaScript after the validator parses the static HTML.

This is primarily an **accessibility** problem. Screen readers and other assistive technologies rely on `aria-labelledby` to announce meaningful labels to users. When the reference is broken, the element effectively has no accessible name, which can make it impossible for users to understand its purpose. Browsers won't throw a visible error, so the issue can go unnoticed without validation or accessibility testing.

To fix the issue, verify that every `id` referenced in `aria-labelledby` exists in the same HTML document. Double-check spelling and casing. If you reference multiple IDs (space-separated), each one must resolve to an existing element.

## Examples

### Incorrect — referencing a non-existent `id`

The `aria-labelledby` attribute points to `"dialog-title"`, but no element with that `id` exists:

```html
<div role="dialog" aria-labelledby="dialog-title">
  <h2 id="dlg-title">Confirm deletion</h2>
  <p>Are you sure you want to delete this item?</p>
</div>
```

### Correct — matching `id` values

Ensure the `id` in the referenced element matches exactly:

```html
<div role="dialog" aria-labelledby="dialog-title">
  <h2 id="dialog-title">Confirm deletion</h2>
  <p>Are you sure you want to delete this item?</p>
</div>
```

### Incorrect — referencing multiple IDs where one is missing

When using multiple IDs, every one must be present. Here, `"note-desc"` doesn't exist:

```html
<section aria-labelledby="note-heading note-desc">
  <h3 id="note-heading">Important note</h3>
  <p id="note-description">Please read carefully before proceeding.</p>
</section>
```

### Correct — all referenced IDs exist

```html
<section aria-labelledby="note-heading note-description">
  <h3 id="note-heading">Important note</h3>
  <p id="note-description">Please read carefully before proceeding.</p>
</section>
```

### Incorrect — case mismatch

IDs are case-sensitive. `"Main-Title"` and `"main-title"` are not the same:

```html
<nav aria-labelledby="Main-Title">
  <h2 id="main-title">Site navigation</h2>
  <ul>
    <li><a href="/">Home</a></li>
  </ul>
</nav>
```

### Correct — consistent casing

```html
<nav aria-labelledby="main-title">
  <h2 id="main-title">Site navigation</h2>
  <ul>
    <li><a href="/">Home</a></li>
  </ul>
</nav>
```

If you don't have a visible labeling element on the page and don't want to add one, consider using `aria-label` instead, which accepts a string value directly rather than referencing another element:

```html
<nav aria-label="Site navigation">
  <ul>
    <li><a href="/">Home</a></li>
  </ul>
</nav>
```