HTML Guides

Text not allowed in element “select” in this context.

Direct text nodes inside select are not permitted content. Browsers typically ignore or mangle that text, leading to inconsistent rendering and confusing experiences for screen reader users. It also breaks conformance, which can impact maintainability and automated tooling. The right approach is to keep instructional text in a corresponding label, or provide a non-selectable prompt using a disabled, selected option. Group labels must be provided with optgroup elements, not free text.

To fix it, remove any raw text inside the select. If you need a prompt, add a first option with value="" and disabled selected hidden for a placeholder-like experience, or rely on a visible label. Ensure all selectable items are wrapped in option, and any grouping uses optgroup with its label attribute. Always associate the select with a label via for/id for accessibility.

Examples

Triggers the error (text node inside `select`)

Please select an option:

<optionvalue="1">Option 1</option>

<optionvalue="2">Option 2</option>

</select>

Correct: move instructions to a `label`

<labelfor="flavor">Please select a flavor:</label>

<selectid="flavor"name="flavor">

<optionvalue="vanilla">Vanilla</option>

<optionvalue="chocolate">Chocolate</option>

</select>

Correct: provide a non-selectable prompt inside `select`

<labelfor="country">Country</label>

<selectid="country"name="country"required>

<optionvalue=""disabledselectedhidden>Select a country</option>

<optionvalue="us">United States</option>

<optionvalue="ca">Canada</option>

</select>

Correct: use `optgroup` for grouping, not free text

<labelfor="city">City</label>

<selectid="city"name="city">

<optgrouplabel="USA">

<optionvalue="nyc">New York</option>

<optionvalue="la">Los Angeles</option>

</optgroup>

<optgrouplabel="Canada">

<optionvalue="toronto">Toronto</option>

<optionvalue="vancouver">Vancouver</option>

</optgroup>

</select>

Correct: full document (for context)

<!doctype html>

<htmllang="en">

<head>

<metacharset="utf-8">

<title>Select without stray text</title>

</head>

<body>

<form>

<labelfor="size">Choose a size:</label>

<selectid="size"name="size">

<optionvalue=""disabledselectedhidden>Select a size</option>

<optionvalue="s">Small</option>

<optionvalue="m">Medium</option>

<optionvalue="l">Large</option>

</select>

</form>

</body>

</html>

Tips:

Put instructions in a label or surrounding text, not inside select.
Every choice must be an option; use optgroup with label to name groups.
For placeholders, prefer a disabled, selected first option; avoid raw text nodes.

Text not allowed in element “ul” in this context.

According to the HTML specification, the content model for <ul> is strictly limited to zero or more <li> elements. Any text node placed directly inside the <ul> violates this rule, even if it seems harmless or invisible. Browsers may still render the page, but the resulting DOM structure is technically invalid and can lead to unpredictable behavior across different browsers and assistive technologies.

This matters for accessibility because screen readers rely on proper list structure to announce the number of items and allow users to navigate between them. Stray text nodes inside a <ul> can confuse these tools, causing list items to be miscounted or the text to be read in an unexpected context.

There are several common scenarios that trigger this error:

Loose text used as a list title. Developers sometimes place a heading or label directly inside the <ul> to describe the list. This text must be moved outside the list element.

Stray   or other entities between list items. This often happens in templating systems or when code is concatenated, where   characters or other text nodes end up between <li> elements. These should be removed entirely, since spacing between list items should be controlled with CSS.

Accidentally placing inline content without wrapping it in <li>. Sometimes content that should be a list item is simply missing its <li> wrapper.

Examples

❌ Text used as a list title inside `<ul>`

<ul>

Fruits

<li>Apple</li>

<li>Orange</li>

<li>Banana</li>

</ul>

The word "Fruits" is a text node directly inside the <ul>, which is not allowed.

✅ Move the title outside the list

<h3>Fruits</h3>

<ul>

<li>Apple</li>

<li>Orange</li>

<li>Banana</li>

</ul>

Using a heading before the list is semantically clear. You can also use a <p> or <span> if a heading isn't appropriate.

❌ ` ` entities between list items

<ul>

<li>First item</li>

<li>Second item</li>

<li>Third item</li>

</ul>

Each   is a text node sitting directly inside the <ul>, triggering the error.

✅ Remove the entities and use CSS for spacing

<ul>

<li>First item</li>

<li>Second item</li>

<li>Third item</li>

</ul>

ulli{

margin-bottom:0.5em;

}

Any visual spacing between list items should be handled with CSS margin or padding, not with HTML entities.

❌ Unwrapped content that should be a list item

<ul>

Eggs

<li>Bread</li>

</ul>

✅ Wrap the content in an `<li>` element

<ul>

<li>Bread</li>

</ul>

The same rules apply to <ol> (ordered lists) and <menu> elements — their direct children must be <li> elements, and text nodes are not permitted. If your list is generated dynamically by a templating engine or JavaScript, check the output carefully for stray whitespace or text that may have been injected between list items.

Text run is not in Unicode Normalization Form C.

Unicode allows some characters to be represented in multiple ways. For example, the accented letter "é" can be stored as a single precomposed character (U+00E9) or as two separate code points: the base letter "e" (U+0065) followed by a combining acute accent (U+0301). While these look identical when rendered, they are fundamentally different at the byte level. Unicode Normalization Form C (NFC) is the canonical form that prefers the single precomposed representation whenever one exists.

The HTML specification and the W3C Character Model for the World Wide Web require that all text in HTML documents be in NFC. This matters for several reasons:

String matching and search: Non-NFC text can cause failures when browsers or scripts try to match strings, compare attribute values, or process CSS selectors. Two visually identical strings in different normalization forms won't match with simple byte comparison.
Accessibility: Screen readers and assistive technologies may behave inconsistently when encountering decomposed character sequences.
Interoperability: Different browsers, search engines, and tools may handle non-NFC text differently, leading to unpredictable behavior.
Fragment identifiers and IDs: If an id attribute contains non-NFC characters, fragment links (#id) may fail to work correctly.

This issue most commonly appears when text is copied from word processors, PDFs, or other applications that use decomposed Unicode forms (NFD), or when content is generated by software that doesn't normalize its output.

How to Fix It

Identify the affected text: The validator will point to the specific line containing non-NFC characters. The characters will often look normal visually, so you'll need to inspect them at the code-point level.
Convert to NFC: Use a text editor or command-line tool that supports Unicode normalization. Many programming languages provide built-in normalization functions.
Prevent future issues: Configure your text editor or build pipeline to save files in NFC. When accepting user input, normalize it server-side before storing or embedding in HTML.

In Python, you can normalize a string:

importunicodedata

normalized=unicodedata.normalize('NFC', original_string)

In JavaScript (Node.js or browser):

constnormalized=originalString.normalize('NFC');

On the command line (using uconv from ICU):

uconv-xNFCinput.html>output.html

Examples

Incorrect (decomposed form — NFD)

In this example, the letter "é" is represented as two code points (e + combining acute accent), which triggers the validation warning. The source may look identical to the correct version, but the underlying bytes differ:

<p>Résumé available upon request.</p>

Correct (precomposed form — NFC)

Here, the same text uses the single precomposed character é (U+00E9):

<p>Résumé available upon request.</p>

Incorrect in attributes

Non-NFC text in attribute values also triggers this issue:

<h2id="resumé">Résumé</h2>

Correct in attributes

<h2id="resumé">Résumé</h2>

While these examples look the same in rendered text, the difference is in how the characters are encoded. To verify your text is in NFC, you can paste it into a Unicode inspector tool or use the normalization functions mentioned above. For further reading, the W3C provides an excellent guide on Normalization in HTML and CSS.

“th” start tag in table body.

th
table

When you write a <table> without explicitly using <thead> and <tbody>, the HTML parser automatically wraps your <tr> elements in an implicit <tbody>. If any of those rows contain <th> elements intended as column headers, the validator flags them because <th> cells in <tbody> are unexpected — the parser sees header cells appearing in what should be the data body of the table.

While <th> elements are technically valid inside <tbody> (for example, as row headers), this warning usually indicates a structural problem: your column headers aren't properly separated from your data rows. Properly structuring your table with <thead> and <tbody> matters for several reasons:

Accessibility: Screen readers use table structure to help users navigate. A <thead> section clearly identifies column headers, making it easier for assistive technology to announce what each data cell represents.
Styling and behavior: CSS selectors like thead th and tbody td let you target headers and data cells independently. Browsers can also use <thead> and <tbody> to enable scrollable table bodies while keeping headers fixed.
Standards compliance: Explicitly defining table sections removes ambiguity and ensures consistent parsing across all browsers.

To fix this issue, wrap the row containing your <th> column headers in a <thead> element, and wrap your data rows in a <tbody> element.

Examples

❌ Incorrect: `<th>` in implicit table body

Here, the parser wraps all rows in an implicit <tbody>, so the <th> elements end up inside the table body:

<table>

<tr>

</tr>

<tr>

</tr>

<tr>

</tr>

</table>

✅ Correct: `<th>` in explicit `<thead>`

Wrapping the header row in <thead> and data rows in <tbody> resolves the issue:

<table>

<thead>

<tr>

</tr>

</thead>

<tbody>

<tr>

</tr>

<tr>

</tr>

</tbody>

</table>

✅ Correct: `<th>` as row headers inside `<tbody>`

If you intentionally use <th> elements inside <tbody> as row headers, add the scope attribute to clarify their purpose. This is valid and won't trigger the warning when the table also has a proper <thead>:

<table>

<thead>

<tr>

<thscope="col">Name</th>

<thscope="col">Age</th>

</tr>

</thead>

<tbody>

<tr>

<thscope="row">Liza</th>

</tr>

<tr>

<thscope="row">Joe</th>

</tr>

</tbody>

</table>

The scope="row" attribute tells assistive technology that these <th> cells are headers for their respective rows, while scope="col" identifies column headers. This combination provides the best accessibility for table data.

The “acronym” element is obsolete. Use the “abbr” element instead.

In earlier versions of HTML, there were two separate elements for shortened forms of words and phrases: <abbr> for abbreviations (like "Dr." or "etc.") and <acronym> for acronyms (like "NASA" or "HTML"). The HTML5 specification eliminated this distinction because acronyms are simply a type of abbreviation. The <abbr> element now covers all cases.

Using the obsolete <acronym> element causes W3C validation errors and has several practical drawbacks:

Standards compliance: The element is not part of the current HTML specification. Validators will flag it as an error, and future browsers are not guaranteed to support it.
Accessibility: Assistive technologies are designed and tested against current standards. While many screen readers still handle <acronym>, relying on an obsolete element risks inconsistent behavior. The <abbr> element has well-defined, standardized accessibility semantics.
Consistency: Using <abbr> for all abbreviations and acronyms simplifies your markup and makes it easier for developers to maintain.

The fix is straightforward: replace every <acronym> tag with <abbr>. The title attribute works the same way on both elements — it provides the expanded form of the abbreviation or acronym that browsers typically display as a tooltip on hover.

Examples

❌ Obsolete: using `<acronym>`

<p>The <acronymtitle="World Wide Web">WWW</acronym> was invented by Tim Berners-Lee.</p>

<p>This page is written in <acronymtitle="HyperText Markup Language">HTML</acronym>.</p>

✅ Fixed: using `<abbr>`

<p>The <abbrtitle="World Wide Web">WWW</abbr> was invented by Tim Berners-Lee.</p>

<p>This page is written in <abbrtitle="HyperText Markup Language">HTML</abbr>.</p>

Using `<abbr>` for both abbreviations and acronyms

Since <abbr> now handles all shortened forms, you can use it consistently throughout your markup:

<p>

Contact <abbrtitle="Doctor">Dr.</abbr> Smith at

<abbrtitle="National Aeronautics and Space Administration">NASA</abbr>

for more information about the <abbrtitle="International Space Station">ISS</abbr>.

</p>

Styling `<abbr>` with CSS

Some browsers apply a default dotted underline to <abbr> elements with a title attribute. You can customize this with CSS:

<style>

abbr[title]{

text-decoration: underline dotted;

cursor: help;

}

</style>

<p>Files are transferred using <abbrtitle="File Transfer Protocol">FTP</abbr>.</p>

If you're migrating a large codebase, a simple find-and-replace of <acronym with <abbr and </acronym> with </abbr> will handle the conversion. No other attributes or content changes are needed — the two elements accept the same attributes and content model.

The “align” attribute on the “td” element is obsolete. Use CSS instead.

In earlier versions of HTML, the align attribute was used directly on <td> (and other table elements like <tr> and <th>) to control horizontal alignment of cell content. Values like left, center, right, and justify were common. HTML5 made this attribute obsolete in favor of CSS, which provides a cleaner separation of content and presentation.

While most browsers still honor the align attribute for backward compatibility, relying on it is discouraged. It violates modern web standards, mixes presentational concerns into your markup, and makes styling harder to maintain. CSS offers far more flexibility — you can target cells by class, use responsive styles, or change alignment through media queries without touching your HTML.

How to fix it

Remove the align attribute from the <td> element.
Apply the CSS text-align property instead, either via an inline style attribute, a <style> block, or an external stylesheet.

The CSS text-align property accepts the same values the old attribute did: left, center, right, and justify.

For vertical alignment, the obsolete valign attribute should similarly be replaced with the CSS vertical-align property.

Examples

❌ Obsolete: using the `align` attribute

<table>

<tr>

<tdalign="center">Centered content</td>

<tdalign="right">Right-aligned content</td>

</tr>

</table>

✅ Fixed: using inline CSS

<table>

<tr>

<tdstyle="text-align: center;">Centered content</td>

<tdstyle="text-align: right;">Right-aligned content</td>

</tr>

</table>

✅ Fixed: using a stylesheet (recommended)

Using classes keeps your HTML clean and makes it easy to update styles across your entire site.

<style>

.text-center{

text-align: center;

}

.text-right{

text-align: right;

}

</style>

<table>

<tr>

<tdclass="text-center">Centered content</td>

<tdclass="text-right">Right-aligned content</td>

</tr>

</table>

✅ Fixed: applying alignment to an entire column

If every cell in a column needs the same alignment, you can target cells by position instead of adding a class to each one.

<style>

td:nth-child(2){

text-align: right;

}

</style>

<table>

<tr>

</tr>

<tr>

<td>Another item</td>

</tr>

</table>

This same approach applies to <th> elements and the <tr> element, which also had an obsolete align attribute in older HTML. In all cases, replace the attribute with the CSS text-align property.

The “aria-checked” attribute must not be used on any “label” element that is associated with a labelable element.

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

The aria-controls attribute establishes a programmatic relationship between a controlling element (like a button, tab, or scrollbar) and the element it controls (like a panel, region, or content area). Assistive technologies such as screen readers use this relationship to help users navigate between related elements — for example, announcing that a button controls a specific panel and allowing the user to jump to it.

When the id referenced in aria-controls doesn't exist in the document, the relationship is broken. Screen readers may attempt to locate the target element and fail silently, or they may announce a control relationship that leads nowhere. This degrades the experience for users who rely on assistive technology and violates the WAI-ARIA specification, which requires that the value of aria-controls be a valid ID reference list pointing to elements in the same document.

Common causes of this error include:

Typos in the id or the aria-controls value.
Dynamically generated content where the controlled element hasn't been rendered yet or has been removed from the DOM.
Copy-paste errors where aria-controls was copied from another component but the corresponding id was not updated.
Referencing elements in iframes or shadow DOM, which are considered separate document contexts.

The aria-controls attribute accepts one or more space-separated ID references. Every listed ID must match an element in the same document.

How to Fix

Verify the target element exists in the document and has the exact id that aria-controls references.
Check for typos — ID matching is case-sensitive, so mainPanel and mainpanel are not the same.
If the controlled element is added dynamically, ensure it is present in the DOM before or at the same time as the controlling element, or update aria-controls programmatically when the target becomes available.
If the controlled element is genuinely absent (e.g., conditionally rendered), remove the aria-controls attribute until the target element exists.

Examples

Incorrect: `aria-controls` references a non-existent ID

<buttonaria-controls="info-panel"aria-expanded="false">

Toggle Info

</button>

<divid="infopanel">

<p>Here is some additional information.</p>

</div>

This triggers the error because aria-controls="info-panel" does not match the actual id of "infopanel" (note the missing hyphen).

Correct: `aria-controls` matches an existing element's ID

<buttonaria-controls="info-panel"aria-expanded="false">

Toggle Info

</button>

<divid="info-panel">

<p>Here is some additional information.</p>

</div>

Correct: Tab and tab panel relationship

<divrole="tablist">

<buttonrole="tab"aria-controls="tab1-panel"aria-selected="true">

Overview

</button>

<buttonrole="tab"aria-controls="tab2-panel"aria-selected="false">

Details

</button>

</div>

<divid="tab1-panel"role="tabpanel">

<p>Overview content goes here.</p>

</div>

<divid="tab2-panel"role="tabpanel"hidden>

<p>Details content goes here.</p>

</div>

Both aria-controls values — tab1-panel and tab2-panel — correctly correspond to elements present in the document.

Correct: Custom scrollbar controlling a region

<divrole="scrollbar"aria-controls="main-content"aria-valuenow="0"aria-valuemin="0"aria-valuemax="100"aria-orientation="vertical"></div>

<divid="main-content"role="region"aria-label="Main content">

<p>Scrollable content goes here.</p>

</div>

Correct: Controlling multiple elements

The aria-controls attribute can reference multiple IDs separated by spaces. Each ID must exist in the document.

<buttonaria-controls="section-a section-b">

Expand All Sections

</button>

<divid="section-a">

<p>Section A content.</p>

</div>

<divid="section-b">

<p>Section B content.</p>

</div>

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

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

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.
Add the missing element. If the descriptive element doesn't exist yet, create it with the matching id.
Remove stale references. If the description is no longer needed, remove the aria-describedby attribute entirely rather than leaving a broken reference.
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:

<labelfor="password">Password</label>

<inputtype="password"id="password"aria-describedby="password-help">

Fixed by adding the referenced element

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

<labelfor="password">Password</label>

<inputtype="password"id="password"aria-describedby="password-help">

<pid="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:

<inputtype="text"id="email"aria-describedby="emailHelp">

<smallid="emailhelp">We'll never share your email.</small>

The fix is to make the id values match exactly:

<inputtype="text"id="email"aria-describedby="email-help">

<smallid="email-help">We'll never share your email.</small>

Multiple IDs with one missing

When listing multiple descriptions, every id must be present:

<inputtype="text"id="username"aria-describedby="format-hint length-hint">

<spanid="format-hint">Letters and numbers only.</span>

Fix it by adding the missing element:

<inputtype="text"id="username"aria-describedby="format-hint length-hint">

<spanid="format-hint">Letters and numbers only.</span>

<spanid="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:

<inputtype="text"id="search">

The “aria-expanded” attribute must not be used on any “summary” element that is a summary for its parent “details” element.

The “aria-hidden” attribute must not be specified on an “input” element whose “type” attribute has the value “hidden”.

An <input type="hidden"> element is inherently invisible to all users. It is not rendered on the page, it cannot receive focus, and browsers automatically exclude it from the accessibility tree. The aria-hidden attribute is designed to hide visible content from assistive technologies like screen readers, but applying it to an element that is already fully hidden serves no purpose.

The HTML specification explicitly forbids the use of aria-hidden on hidden inputs. This restriction exists because combining the two is semantically meaningless — you cannot "hide from assistive technologies" something that is already invisible to everyone. Validators flag this as an error to encourage clean, standards-compliant markup and to help developers avoid misunderstandings about how ARIA attributes interact with native HTML semantics.

This issue commonly arises when aria-hidden="true" is applied broadly to a group of elements (for example, via a script or template) without checking whether specific children already handle their own visibility. It can also happen when developers add ARIA attributes as a precaution, not realizing that the native behavior of type="hidden" already covers accessibility concerns.

To fix this, remove the aria-hidden attribute from any <input> element whose type is hidden. No replacement is needed — the browser already handles everything correctly.

Examples

Incorrect

Adding aria-hidden to a hidden input triggers a validation error:

<formaction="/submit"method="post">

<inputtype="hidden"aria-hidden="true"name="month"value="10">

<inputtype="hidden"aria-hidden="true"name="csrf_token"value="abc123">

<buttontype="submit">Submit</button>

</form>

Correct

Remove the aria-hidden attribute entirely. The hidden inputs are already inaccessible to all users by default:

<formaction="/submit"method="post">

<inputtype="hidden"name="month"value="10">

<inputtype="hidden"name="csrf_token"value="abc123">

<buttontype="submit">Submit</button>

</form>

When `aria-hidden` is appropriate

The aria-hidden attribute is intended for elements that are visually present but should be hidden from assistive technologies, such as decorative icons:

<buttontype="button">

<spanaria-hidden="true">★</span>

Favorite

</button>

In this case, the decorative star is visible on screen but irrelevant to screen reader users, so aria-hidden="true" correctly prevents it from being announced. This is the proper use case — hiding visible content from the accessibility tree, not redundantly marking already-hidden elements.

The “aria-hidden” attribute must not be specified on the “link” element.

The <link> element is used to define relationships between the current document and external resources—most commonly stylesheets, favicons, and preloaded assets. It is a void element (it has no closing tag) and it produces no rendered content on the page. Because <link> elements are inherently non-visible and already absent from the accessibility tree, the aria-hidden attribute serves no purpose on them.

The aria-hidden attribute is designed to control the visibility of rendered content for assistive technologies like screen readers. When set to "true" on a visible element, it tells assistive technologies to skip that element and its descendants. Applying it to a <link> element is contradictory—you're trying to hide something from assistive technologies that was never exposed to them in the first place. The HTML specification explicitly disallows this combination, and the W3C validator will flag it as an error.

This issue sometimes arises when developers apply aria-hidden broadly through templating systems, JavaScript frameworks, or build tools that inject attributes across multiple element types without distinguishing between visible content elements and metadata elements. It can also happen when copying attribute patterns from <a> elements (which share the word "link" conceptually but are entirely different elements) onto <link> elements.

How to fix it

The fix is straightforward: remove the aria-hidden attribute from the <link> element. No replacement or alternative attribute is needed because <link> elements are already invisible to assistive technologies.

If your original intent was to hide a visible element from screen readers, make sure you're applying aria-hidden to the correct element—a rendered content element such as <div>, <span>, <img>, or <a>, not a metadata element like <link>.

Examples

Incorrect: `aria-hidden` on a `<link>` element

<linkrel="stylesheet"href="styles.css"aria-hidden="true">

<linkrel="icon"href="favicon.ico"aria-hidden="true">

<linkrel="preload"href="font.woff2"as="font"type="font/woff2"aria-hidden="true">

Correct: `<link>` without `aria-hidden`

<linkrel="stylesheet"href="styles.css">

<linkrel="icon"href="favicon.ico">

<linkrel="preload"href="font.woff2"as="font"type="font/woff2">

Correct: `aria-hidden` used on a visible element instead

If you need to hide a decorative element from screen readers, apply aria-hidden to the rendered element itself:

<linkrel="stylesheet"href="styles.css">

<divaria-hidden="true">

<imgsrc="decorative-swirl.png"alt="">

</div>

Incorrect vs. correct in a full document

<!DOCTYPE html>

<htmllang="en">

<head>

<metacharset="utf-8">

<linkrel="stylesheet"href="styles.css"aria-hidden="true">

</head>

<body>

<p>Hello, world!</p>

</body>

</html>

<!DOCTYPE html>

<htmllang="en">

<head>

<metacharset="utf-8">

<linkrel="stylesheet"href="styles.css">

</head>

<body>

<p>Hello, world!</p>

</body>

</html>

The “aria-hidden” attribute must not be used on any “label” element that is associated with a labelable element.

The “aria-label” attribute must not be specified on any “a” element unless the element has a “role” value other than “caption”, “code”, “deletion”, “emphasis”, “generic”, “insertion”, “paragraph”, “presentation”, “strong”, “subscript”, or “superscript”.

The “aria-label” attribute must not be specified on any “div” element unless the element has a “role” value other than “caption”, “code”, “deletion”, “emphasis”, “generic”, “insertion”, “paragraph”, “presentation”, “strong”, “subscript”, or “superscript”.

The “aria-label” attribute must not be specified on any “i” element unless the element has a “role” value other than “caption”, “code”, “deletion”, “emphasis”, “generic”, “insertion”, “paragraph”, “presentation”, “strong”, “subscript”, or “superscript”.

The “aria-label” attribute must not be specified on any “menu-item” element unless the element has a “role” value other than “caption”, “code”, “deletion”, “emphasis”, “generic”, “insertion”, “paragraph”, “presentation”, “strong”, “subscript”, or “superscript”.

The “aria-label” attribute must not be specified on any “span” element unless the element has a “role” value other than “caption”, “code”, “deletion”, “emphasis”, “generic”, “insertion”, “paragraph”, “presentation”, “strong”, “subscript”, or “superscript”.

The “aria-label” attribute must not be specified on any “time” element unless the element has a “role” value other than “caption”, “code”, “deletion”, “emphasis”, “generic”, “insertion”, “paragraph”, “presentation”, “strong”, “subscript”, or “superscript”.

The “aria-label” attribute must not be used on any “label” element that is an ancestor of a labelable element.

The “aria-label” attribute must not be used on any “label” element that is associated with a labelable element.

The “aria-labelledby” attribute must not be specified on any “div” element unless the element has a “role” value other than “caption”, “code”, “deletion”, “emphasis”, “generic”, “insertion”, “paragraph”, “presentation”, “strong”, “subscript”, or “superscript”.

The “aria-labelledby” attribute must not be specified on any “span” element unless the element has a “role” value other than “caption”, “code”, “deletion”, “emphasis”, “generic”, “insertion”, “paragraph”, “presentation”, “strong”, “subscript”, or “superscript”.

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

aria-labelledby

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:

<divrole="dialog"aria-labelledby="dialog-title">

<h2id="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:

<divrole="dialog"aria-labelledby="dialog-title">

<h2id="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:

<sectionaria-labelledby="note-heading note-desc">

<h3id="note-heading">Important note</h3>

<pid="note-description">Please read carefully before proceeding.</p>

</section>

Correct — all referenced IDs exist

<sectionaria-labelledby="note-heading note-description">

<h3id="note-heading">Important note</h3>

<pid="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:

<navaria-labelledby="Main-Title">

<h2id="main-title">Site navigation</h2>

<ul>

</ul>

</nav>

Correct — consistent casing

<navaria-labelledby="main-title">

<h2id="main-title">Site navigation</h2>

<ul>

</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:

<navaria-label="Site navigation">

<ul>

</ul>

</nav>

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

aria-owns

The aria-owns attribute is used to define parent-child relationships in the accessibility tree that aren't reflected in the DOM structure. For example, if a menu visually "owns" items that are placed elsewhere in the markup (perhaps for layout reasons), aria-owns tells assistive technologies that those elements should be treated as children of the owning element. The attribute accepts a space-separated list of one or more IDs.

According to the WAI-ARIA specification, each ID referenced by aria-owns must correspond to an element in the same document. If no matching element is found, the relationship is broken and the accessibility tree becomes inaccurate. This can confuse screen readers and other assistive technologies, potentially making parts of your page inaccessible or misrepresented to users who rely on them.

Common causes of this error:

Typos in the ID value — a small misspelling like aria-owns="drpdown-menu" instead of aria-owns="dropdown-menu".
Referencing an element that doesn't exist — the target element was removed or never added to the page.
Referencing an element in a different document — the target lives inside an <iframe> or a shadow DOM, which are separate document contexts.
Dynamic content timing — the referenced element is added to the DOM by JavaScript after validation or after the aria-owns relationship is evaluated.

How to fix it:

Check that every ID in the aria-owns value exactly matches an id attribute on an element in the same document.
Look for typos or case mismatches — IDs are case-sensitive.
If the target element is inside an <iframe>, restructure your markup so both elements are in the same document, or use a different ARIA approach.
If the element is added dynamically, ensure it exists in the DOM before the aria-owns relationship is needed by assistive technologies.

Examples

Incorrect — referencing a nonexistent ID

The element with id="dropdown-items" does not exist anywhere in the document, so the aria-owns reference is broken.

<buttonaria-owns="dropdown-items">Open Menu</button>

Incorrect — typo in the referenced ID

The button references "menu-lst" but the actual element has id="menu-list".

<buttonaria-owns="menu-lst">Options</button>

<ulid="menu-list">

<li>Option A</li>

<li>Option B</li>

</ul>

Correct — referenced ID exists in the same document

The aria-owns value matches the id of an element present in the same page.

<buttonaria-owns="menu-list">Options</button>

<ulid="menu-list">

<li>Option A</li>

<li>Option B</li>

</ul>

Correct — multiple IDs referenced

When aria-owns lists multiple IDs, each one must have a corresponding element in the document.

<divrole="tree"aria-owns="branch1 branch2 branch3">

File Explorer

</div>

<divrole="treeitem"id="branch1">Documents</div>

<divrole="treeitem"id="branch2">Pictures</div>

<divrole="treeitem"id="branch3">Music</div>

Complete valid example

<!DOCTYPE html>

<htmllang="en">

<head>

<title>aria-owns Example</title>

</head>

<body>

<divrole="combobox"aria-expanded="true"aria-owns="suggestions">

<inputtype="text"aria-autocomplete="list">

</div>

<ulid="suggestions"role="listbox">

<lirole="option">Apple</li>

<lirole="option">Banana</li>

<lirole="option">Cherry</li>

</ul>

</body>

</html>

In this example, the combobox uses aria-owns to claim the suggestions listbox as its child in the accessibility tree, even though the <ul> is a sibling in the DOM. Because the id="suggestions" element exists in the same document, the reference is valid and assistive technologies can correctly associate the two.

Examples

Triggers the error (text node inside select)

Correct: move instructions to a label

Correct: provide a non-selectable prompt inside select

Correct: use optgroup for grouping, not free text

Correct: full document (for context)

Examples

❌ Text used as a list title inside <ul>

✅ Move the title outside the list

❌ &nbsp; entities between list items

✅ Remove the entities and use CSS for spacing

❌ Unwrapped content that should be a list item

✅ Wrap the content in an <li> element

How to Fix It

Examples

Incorrect (decomposed form — NFD)

Correct (precomposed form — NFC)

Incorrect in attributes

Correct in attributes

Examples

❌ Incorrect: <th> in implicit table body

✅ Correct: <th> in explicit <thead>

✅ Correct: <th> as row headers inside <tbody>

Examples

❌ Obsolete: using <acronym>

✅ Fixed: using <abbr>

Using <abbr> for both abbreviations and acronyms

Styling <abbr> with CSS

How to fix it

Examples

❌ Obsolete: using the align attribute

✅ Fixed: using inline CSS

✅ Fixed: using a stylesheet (recommended)

✅ Fixed: applying alignment to an entire column

Example with the issue

Fixed example using a native checkbox

Fixed example using a custom toggle

How to Fix

Examples

Incorrect: aria-controls references a non-existent ID

Correct: aria-controls matches an existing element's ID

Correct: Tab and tab panel relationship

Correct: Custom scrollbar controlling a region

Correct: Controlling multiple elements

How to fix it

Examples

Broken reference (triggers the error)

Fixed by adding the referenced element

Broken reference due to a typo

Multiple IDs with one missing

Removing the attribute when no description is needed

Incorrect Example

Correct Example

Examples

Incorrect

Correct

When aria-hidden is appropriate

How to fix it

Examples

Incorrect: aria-hidden on a <link> element

Correct: <link> without aria-hidden

Correct: aria-hidden used on a visible element instead

Incorrect vs. correct in a full document

Incorrect example

Correct examples

HTML Examples

❌ Invalid: aria-label on an <a> without href

✅ Fix option 1: Add an href

✅ Fix option 2: Use a <button> instead

✅ Fix option 3: Add an explicit role that supports naming

HTML Examples

❌ Invalid: aria-label on a plain div

✅ Fix: Add an appropriate role

✅ Fix: Use a semantic element instead

HTML Examples

❌ Invalid: aria-label on a plain <i> element

✅ Fix 1: Decorative icon — hide it, label the parent

✅ Fix 2: Meaningful icon — assign role="img"

HTML Examples

Triggers the error (text node inside `select`)

Correct: move instructions to a `label`

Correct: provide a non-selectable prompt inside `select`

Correct: use `optgroup` for grouping, not free text

❌ Text used as a list title inside `<ul>`

❌ ` ` entities between list items

✅ Wrap the content in an `<li>` element

❌ Incorrect: `<th>` in implicit table body

✅ Correct: `<th>` in explicit `<thead>`

✅ Correct: `<th>` as row headers inside `<tbody>`

❌ Obsolete: using `<acronym>`

✅ Fixed: using `<abbr>`

Using `<abbr>` for both abbreviations and acronyms

Styling `<abbr>` with CSS

❌ Obsolete: using the `align` attribute

Incorrect: `aria-controls` references a non-existent ID

Correct: `aria-controls` matches an existing element's ID

When `aria-hidden` is appropriate

Incorrect: `aria-hidden` on a `<link>` element

Correct: `<link>` without `aria-hidden`

Correct: `aria-hidden` used on a visible element instead

❌ Invalid: `aria-label` on an `<a>` without `href`

✅ Fix option 1: Add an `href`

✅ Fix option 2: Use a `<button>` instead

❌ Invalid: `aria-label` on a plain `div`

✅ Fix: Add an appropriate `role`

❌ Invalid: `aria-label` on a plain `<i>` element

✅ Fix 2: Meaningful icon — assign `role="img"`

❌ Invalid: `aria-label` on an element with implicit `generic` role

✅ Valid: adding an explicit `role` that supports `aria-label`

❌ Invalid: `aria-label` on a plain `span`

✅ Fixed: hide the decorative `span` and provide text another way

❌ Invalid: `aria-label` on `<time>`

✅ Fixed: Remove `aria-label` and use clear visible text

Invalid: `aria-label` on a `label` that wraps an input

Fixed: move `aria-label` to the input

❌ Invalid: `aria-labelledby` on a plain `div`

✅ Fixed: Add a meaningful `role` to the `div`

❌ Invalid: `aria-labelledby` on a plain `span`

✅ Fix: Add an appropriate `role`

Incorrect — referencing a non-existent `id`

Correct — matching `id` values

Validate at scale.
Ship accessible websites, faster.