HTML Guides
Learn how to identify and fix common HTML validation errors flagged by the W3C Validator — so your pages are standards-compliant and render correctly across every browser. Also check our Accessibility Guides.
A <th> with a colspan wider than the rest of the table adds the columns in the reported range, and no <td> or <th> begins in any of them.
The validator builds the table grid from each row's cells and their colspan values. A <th colspan="4"> that starts in column 2 covers columns 2 to 5, so the table has at least five columns. The HTML table model requires every column to have at least one cell that starts in it, and a cell that only crosses a column through colspan doesn't count. If the other rows have only two cells, nothing starts in columns 3 to 5, and the validator reports them as the range 3…5, naming th as the element that created them.
This often happens with header rows that group headings over more columns than the body has, or with a colspan left over from a wider version of the table. The short rows usually add a warning too: "A table row was 2 columns wide, which is less than the column count established by the first row (5)." When only one column is empty, the validator names that single column ("Table column 3") instead of a range.
To fix it, lower the colspan so the header covers only the columns the rows use. If the table really needs the extra columns, add cells to the other rows so a cell starts in each of them.
Invalid example
The second heading spans four columns, but each body row has only two cells:
<table>
<tr>
<th>Term</th>
<th colspan="4">Dates</th>
</tr>
<tr>
<td>Autumn</td>
<td>September to December</td>
</tr>
</table>
Valid example
Without the colspan, the header and the body both have two columns:
<table>
<tr>
<th>Term</th>
<th>Dates</th>
</tr>
<tr>
<td>Autumn</td>
<td>September to December</td>
</tr>
</table>
The HTML specification defines a strict content model for tables. The <td> (table data) element represents a single cell containing data, and it can only appear as a child of a <tr> element. Table sectioning elements like <tbody>, <thead>, and <tfoot> may only contain <tr> elements as direct children — not <td> or <th> cells directly. When the validator encounters a <td> start tag inside a table body (or other section) without a wrapping <tr>, it reports this error.
This issue typically arises in a few common scenarios:
- A missing
<tr>wrapper — the developer placed cells directly inside<tbody>or<table>without creating a row. - A prematurely closed
<tr>— a typo or stray</tr>tag ended the row too early, leaving subsequent<td>elements orphaned. - Dynamically generated HTML — template engines or JavaScript may produce table markup where
<tr>elements are accidentally omitted.
Why this matters
- Standards compliance: The HTML living standard explicitly requires
<td>elements to be children of<tr>. Violating this produces invalid markup. - Browser inconsistency: Browsers will attempt to error-correct by implicitly creating
<tr>elements, but different browsers may interpret the malformed structure differently, leading to unpredictable rendering. - Accessibility: Screen readers and assistive technologies rely on correct table structure to navigate rows and columns. Missing
<tr>elements can confuse these tools, making the data harder or impossible to understand for users who depend on them. - Maintainability: Invalid table markup is harder to style with CSS and harder for other developers to understand and maintain.
Examples
Incorrect — <td> directly inside <tbody>
The <td> elements are children of <tbody> instead of being wrapped in a <tr>:
<table>
<tbody>
<td>Name</td>
<td>Age</td>
</tbody>
</table>
Correct — <td> wrapped in <tr>
Adding a <tr> element creates a valid table row:
<table>
<tbody>
<tr>
<td>Name</td>
<td>Age</td>
</tr>
</tbody>
</table>
Incorrect — prematurely closed <tr> leaves orphaned cells
Here the first </tr> closes the row too early, so the second <td> ends up directly inside <tbody>:
<table>
<tbody>
<tr>
<td>Cell 1</td>
</tr>
<td>Cell 2</td>
<td>Cell 3</td>
</tbody>
</table>
Correct — all cells placed inside proper rows
Either include all cells in one row, or create multiple rows as needed:
<table>
<tbody>
<tr>
<td>Cell 1</td>
<td>Cell 2</td>
<td>Cell 3</td>
</tr>
</tbody>
</table>
Or, if you intended two separate rows:
<table>
<tbody>
<tr>
<td>Cell 1</td>
</tr>
<tr>
<td>Cell 2</td>
<td>Cell 3</td>
</tr>
</tbody>
</table>
Incorrect — <td> directly inside <table> with no sections or rows
<table>
<td>Alpha</td>
<td>Beta</td>
</table>
Correct — minimal valid table structure
While <tbody> is optional (browsers add it implicitly), a <tr> is always required:
<table>
<tr>
<td>Alpha</td>
<td>Beta</td>
</tr>
</table>
To fix this error, inspect your table markup and ensure every <td> (and <th>) element is a direct child of a <tr>. Check for stray closing </tr> tags that might end rows prematurely, and verify that any dynamically generated table content produces <tr> wrappers around cell elements.
A <details> element can hold text only after its <summary>, so any text before the <summary>, even an invisible character, is invalid.
The content model of <details> is one <summary> element followed by flow content, which means the <summary> has to come first. Spaces, tabs and line breaks between <details> and <summary> are fine. Any other character counts as text, and text in that position breaks the rule. Text after the <summary> is allowed, because it's part of the content the widget shows when it opens.
Invisible characters cause this error often. Pasting from a word processor or a rich text editor can leave a non-breaking space ( ) or a zero-width space (​, U+200B) right after the opening <details> tag. The page looks normal, but the validator still finds text there. Search the source for those characters and delete them.
If the text is meant as the label, move it into the <summary>. If it's part of the content, put it after the <summary>. A <details> with no <summary> at all also triggers this error, together with one saying the required <summary> child is missing.
Invalid example
<details>
Shipping information
<summary>Shipping</summary>
<p>Orders ship within two days.</p>
</details>
Valid example
<details>
<summary>Shipping information</summary>
<p>Orders ship within two days.</p>
</details>
The <iframe> element is designed to embed another browsing context (essentially a nested document) within the current page. According to the HTML specification, the content model of <iframe> is nothing — it must not contain any text nodes or child elements. Any text placed directly inside the <iframe> tags is invalid HTML.
Historically, some older HTML versions allowed fallback text inside <iframe> for browsers that didn't support iframes. This is no longer the case in modern HTML. All current browsers support <iframe>, so there is no need for fallback content. The W3C validator flags this as an error because text or elements between the <iframe> tags violate the current HTML specification.
There are two valid ways to specify the content an iframe should display:
srcattribute — Provide a URL pointing to the document you want to embed.srcdocattribute — Provide inline HTML content directly as the attribute's value. The HTML is written as a string with appropriate character escaping (e.g.,<for<and"for"if using double-quoted attributes).
If you were using text inside <iframe> as a description or fallback, consider using the title attribute instead to provide an accessible label for the embedded content.
Examples
❌ Invalid: text inside the <iframe> element
<iframe>Some content here</iframe>
<iframe><p>This is my embedded content.</p></iframe>
Both of these will trigger the "Text not allowed in element iframe in this context" error.
✅ Valid: using the src attribute
<iframe src="https://example.com" title="Example website"></iframe>
This loads the document at the specified URL inside the iframe.
✅ Valid: using the srcdoc attribute
<iframe srcdoc="<p>This is my embedded content.</p>" title="Inline content"></iframe>
This renders the inline HTML provided in the srcdoc attribute. Note that HTML special characters must be escaped when the attribute value is enclosed in double quotes.
✅ Valid: self-closing style (empty element)
<iframe src="https://example.com" title="Example website"></iframe>
The <iframe> element requires a closing tag, but nothing should appear between the opening and closing tags. Keeping the element empty is the correct approach.
✅ Valid: adding an accessible label with title
If your original intent was to describe the iframe's content for users or assistive technologies, use the title attribute:
<iframe src="/embedded-report.html" title="Monthly sales report"></iframe>
The title attribute provides a label that screen readers can announce, improving the accessibility of the embedded content.
Text content cannot be placed directly inside an ol element. All text within an ordered list must be wrapped in li elements.
The ol element accepts only li, script, and template elements as children. Any bare text node placed directly between <ol> and </ol> (or between </li> and <li>) is invalid. This includes whitespace-only text nodes in some edge cases, but the validator typically flags visible text content.
This error often appears when list items are missing their <li> tags, or when extra text (like a heading or description) is placed inside the ol instead of before or after it.
Invalid example
<ol>
Some introductory text
<li>First item</li>
<li>Second item</li>
</ol>
Valid example
Move the text outside the ol, or wrap each piece of text in an li element:
<p>Some introductory text</p>
<ol>
<li>First item</li>
<li>Second item</li>
</ol>
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)
<select>
Please select an option:
<option value="1">Option 1</option>
<option value="2">Option 2</option>
</select>
Correct: move instructions to a label
<label for="flavor">Please select a flavor:</label>
<select id="flavor" name="flavor">
<option value="vanilla">Vanilla</option>
<option value="chocolate">Chocolate</option>
</select>
Correct: provide a non-selectable prompt inside select
<label for="country">Country</label>
<select id="country" name="country" required>
<option value="" disabled selected hidden>Select a country</option>
<option value="us">United States</option>
<option value="ca">Canada</option>
</select>
Correct: use optgroup for grouping, not free text
<label for="city">City</label>
<select id="city" name="city">
<optgroup label="USA">
<option value="nyc">New York</option>
<option value="la">Los Angeles</option>
</optgroup>
<optgroup label="Canada">
<option value="toronto">Toronto</option>
<option value="vancouver">Vancouver</option>
</optgroup>
</select>
Correct: full document (for context)
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Select without stray text</title>
</head>
<body>
<form>
<label for="size">Choose a size:</label>
<select id="size" name="size">
<option value="" disabled selected hidden>Select a size</option>
<option value="s">Small</option>
<option value="m">Medium</option>
<option value="l">Large</option>
</select>
</form>
</body>
</html>
Tips:
- Put instructions in a
labelor surrounding text, not insideselect. - Every choice must be an
option; useoptgroupwithlabelto name groups. - For placeholders, prefer a disabled, selected first
option; avoid raw text nodes.
An <svg> element can contain child elements and the whitespace between them, but no text of its own.
The most common cause is a typo in the start tag. An extra >, as in <svg viewBox="0 0 24 24">>, closes the tag and leaves the second > behind as a text character inside the SVG. The validator also reports this error for a entity, a stray word, or fallback text such as "Close" written between the child elements. Line breaks and indentation between elements are fine.
Browsers don't draw text that sits directly inside <svg>, so the graphic looks correct and the mistake is easy to miss. To show text in the graphic, put it in a <text> element. To give the graphic an accessible name, add a <title> element inside the <svg>.
Text placed directly inside a <g> or another SVG container triggers the same kind of error, naming that element instead of svg.
Invalid example: extra > in the start tag
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24">>
<path d="M5 15.5L12 8.5L19 15.5" fill="none" stroke="currentColor" stroke-width="2" />
</svg>
Valid example
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24">
<path d="M5 15.5L12 8.5L19 15.5" fill="none" stroke="currentColor" stroke-width="2" />
</svg>
Invalid example: text used as a label
<svg viewBox="0 0 24 24" width="24" height="24">
Close
<path d="M6 6L18 18M18 6L6 18" stroke="currentColor" stroke-width="2" />
</svg>
Valid example: label in a title element
<svg viewBox="0 0 24 24" width="24" height="24" role="img">
<title>Close</title>
<path d="M6 6L18 18M18 6L6 18" stroke="currentColor" stroke-width="2" />
</svg>
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>
ul li {
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>
<li>Milk</li>
Eggs
<li>Bread</li>
</ul>
✅ Wrap the content in an <li> element
<ul>
<li>Milk</li>
<li>Eggs</li>
<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.
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
idattribute 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:
import unicodedata
normalized = unicodedata.normalize('NFC', original_string)
In JavaScript (Node.js or browser):
const normalized = originalString.normalize('NFC');
On the command line (using uconv from ICU):
uconv -x NFC input.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:
<!-- "é" here is stored as U+0065 U+0301 (decomposed) -->
<p>Résumé available upon request.</p>
Correct (precomposed form — NFC)
Here, the same text uses the single precomposed character é (U+00E9):
<!-- "é" here is stored as U+00E9 (precomposed) -->
<p>Résumé available upon request.</p>
Incorrect in attributes
Non-NFC text in attribute values also triggers this issue:
<!-- The id contains a decomposed character -->
<h2 id="resumé">Résumé</h2>
Correct in attributes
<!-- The id uses the precomposed NFC character -->
<h2 id="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.
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 thandtbody tdlet 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>
<th>Name</th>
<th>Age</th>
</tr>
<tr>
<td>Liza</td>
<td>49</td>
</tr>
<tr>
<td>Joe</td>
<td>47</td>
</tr>
</table>
✅ Correct: <th> in explicit <thead>
Wrapping the header row in <thead> and data rows in <tbody> resolves the issue:
<table>
<thead>
<tr>
<th>Name</th>
<th>Age</th>
</tr>
</thead>
<tbody>
<tr>
<td>Liza</td>
<td>49</td>
</tr>
<tr>
<td>Joe</td>
<td>47</td>
</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>
<th scope="col">Name</th>
<th scope="col">Age</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">Liza</th>
<td>49</td>
</tr>
<tr>
<th scope="row">Joe</th>
<td>47</td>
</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.
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 <acronym title="World Wide Web">WWW</acronym> was invented by Tim Berners-Lee.</p>
<p>This page is written in <acronym title="HyperText Markup Language">HTML</acronym>.</p>
✅ Fixed: using <abbr>
<p>The <abbr title="World Wide Web">WWW</abbr> was invented by Tim Berners-Lee.</p>
<p>This page is written in <abbr title="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 <abbr title="Doctor">Dr.</abbr> Smith at
<abbr title="National Aeronautics and Space Administration">NASA</abbr>
for more information about the <abbr title="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 <abbr title="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.
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
alignattribute from the<td>element. - Apply the CSS
text-alignproperty instead, either via an inlinestyleattribute, 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>
<td align="center">Centered content</td>
<td align="right">Right-aligned content</td>
</tr>
</table>
✅ Fixed: using inline CSS
<table>
<tr>
<td style="text-align: center;">Centered content</td>
<td style="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>
<td class="text-center">Centered content</td>
<td class="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>
<td>Item</td>
<td>$9.99</td>
</tr>
<tr>
<td>Another item</td>
<td>$14.50</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 is redundant on <input type="radio"> because the browser already exposes the checked state to assistive technologies through the native checked property.
Radio inputs have built-in semantics that map directly to the aria-checked state. When a radio button is selected, the browser automatically communicates that state to the accessibility tree. Adding aria-checked manually creates a conflict: the attribute could fall out of sync with the actual checked state, and it overrides the native semantics that assistive technologies already understand.
The ARIA in HTML specification explicitly prohibits aria-checked on <input type="radio">. This falls under the general principle of not using ARIA attributes to duplicate what HTML already provides natively.
If you need to create custom styled radio buttons that don't use native <input> elements, then aria-checked belongs on an element with role="radio". But when using a standard <input type="radio">, the checked attribute (or the DOM property) is all you need.
Invalid example
<label>
<input type="radio" name="color" value="red" aria-checked="true" checked>
Red
</label>
<label>
<input type="radio" name="color" value="blue" aria-checked="false">
Blue
</label>
Valid example
Remove aria-checked and rely on the native checked attribute:
<label>
<input type="radio" name="color" value="red" checked>
Red
</label>
<label>
<input type="radio" name="color" value="blue">
Blue
</label>
If you need a custom radio group without native inputs, use role="radio" with aria-checked:
<div role="radiogroup" aria-label="Color">
<span role="radio" aria-checked="true" tabindex="0">Red</span>
<span role="radio" aria-checked="false" tabindex="-1">Blue</span>
</div>
The aria-checked attribute is not allowed on a label element when that label is associated with a form control like a checkbox or radio button.
When a label is associated with a labelable element (via the for attribute or by nesting), the label acts as an accessible name provider — it doesn't represent the control's state itself. The aria-checked attribute is meant for elements that act as a checkbox or radio button, such as elements with role="checkbox" or role="switch", not for labels that merely describe one.
Adding aria-checked to a label creates conflicting semantics. Assistive technologies already read the checked state from the associated input element, so duplicating or overriding that state on the label causes confusion.
If you need a custom toggle or checkbox, apply aria-checked to the element that has the interactive role, not to the label.
Example with the issue
<label for="notifications" aria-checked="true">Enable notifications</label>
<input type="checkbox" id="notifications" checked>
Fixed example using a native checkbox
<label for="notifications">Enable notifications</label>
<input type="checkbox" id="notifications" checked>
The native <input type="checkbox"> already communicates its checked state to assistive technologies — no aria-checked is needed anywhere.
Fixed example using a custom toggle
If you're building a custom control without a native checkbox, apply aria-checked to the element with the appropriate role:
<span id="toggle-label">Enable notifications</span>
<span role="switch" tabindex="0" aria-checked="true" aria-labelledby="toggle-label"></span>
Here, aria-checked is correctly placed on the element with role="switch", which is the interactive control. The label is a separate <span> referenced via aria-labelledby, keeping roles and states cleanly separated.
A <label> that points at a form control with its for attribute can't carry aria-controls, because that relationship belongs on the control itself.
aria-controls takes the id of the element whose content or visibility the current element changes, such as the panel a tab shows or the slide a carousel control brings into view. Screen readers report that relationship on the focused element, and some let users jump from there to the controlled region.
Once a <label> is associated with a labelable element (<input>, <select>, <textarea>, <button> and a few others), it has no role of its own. Its text becomes the control's accessible name, and a click on it goes to the control. Keyboard and screen reader users interact with the control, not with the label, so aria-controls on the label sits on an element they never reach.
The error often comes from CSS-only tabs or sliders built from radio buttons, where each <label> is styled as the visible trigger and the <input> is hidden. Put aria-controls on each <input> and leave the <label> with just its for attribute. If you hide the radio buttons, use a visually hidden technique rather than display: none, so they stay focusable and screen readers can still announce them.
Invalid example
<input type="radio" name="slides" id="slide-1" checked>
<label for="slide-1" aria-controls="panel-1">First slide</label>
<input type="radio" name="slides" id="slide-2">
<label for="slide-2" aria-controls="panel-2">Second slide</label>
<div id="panel-1">First slide content</div>
<div id="panel-2">Second slide content</div>
Valid example
<input type="radio" name="slides" id="slide-1" aria-controls="panel-1" checked>
<label for="slide-1">First slide</label>
<input type="radio" name="slides" id="slide-2" aria-controls="panel-2">
<label for="slide-2">Second slide</label>
<div id="panel-1">First slide content</div>
<div id="panel-2">Second slide content</div>
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
idor thearia-controlsvalue. - Dynamically generated content where the controlled element hasn't been rendered yet or has been removed from the DOM.
- Copy-paste errors where
aria-controlswas copied from another component but the correspondingidwas 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
idthataria-controlsreferences. - Check for typos — ID matching is case-sensitive, so
mainPanelandmainpanelare 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-controlsprogrammatically when the target becomes available. - If the controlled element is genuinely absent (e.g., conditionally rendered), remove the
aria-controlsattribute until the target element exists.
Examples
Incorrect: aria-controls references a non-existent ID
<button aria-controls="info-panel" aria-expanded="false">
Toggle Info
</button>
<div id="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
<button aria-controls="info-panel" aria-expanded="false">
Toggle Info
</button>
<div id="info-panel">
<p>Here is some additional information.</p>
</div>
Correct: Tab and tab panel relationship
<div role="tablist">
<button role="tab" aria-controls="tab1-panel" aria-selected="true">
Overview
</button>
<button role="tab" aria-controls="tab2-panel" aria-selected="false">
Details
</button>
</div>
<div id="tab1-panel" role="tabpanel">
<p>Overview content goes here.</p>
</div>
<div id="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
<div role="scrollbar" aria-controls="main-content" aria-valuenow="0" aria-valuemin="0" aria-valuemax="100" aria-orientation="vertical"></div>
<div id="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.
<button aria-controls="section-a section-b">
Expand All Sections
</button>
<div id="section-a">
<p>Section A content.</p>
</div>
<div id="section-b">
<p>Section B content.</p>
</div>
The aria-describedby attribute is not allowed on a <label> element when that <label> contains a labelable element (such as <input>, <select>, <textarea>, or <button>).
aria-describedby points assistive technology at one or more elements that describe a control, referenced by their id. The description belongs on the control being described, not on its label. When a <label> wraps the control, the label already supplies the accessible name, so adding a description there leaves it unclear what the text is meant to describe.
That ambiguity is why the spec rejects the attribute on a <label> that is an ancestor of a labelable element. A "labelable element" is any element a <label> can be associated with: <input> (except type="hidden"), <select>, <textarea>, <button>, <meter>, <output>, and <progress>.
Move aria-describedby onto the form control so the description is announced for the element it actually refers to.
Examples
Invalid: aria-describedby on a label that wraps an input
<label aria-describedby="password-hint">
Password
<input type="password" name="password">
</label>
<span id="password-hint">Use at least 8 characters.</span>
Fixed: move it to the input
<label>
Password
<input type="password" name="password" aria-describedby="password-hint">
</label>
<span id="password-hint">Use at least 8 characters.</span>
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
idvalue — thearia-describedbyvalue doesn't match the target element'sidexactly (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
idwas changed or the element was removed, but thearia-describedbyreference 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-describedbyagainst theidof the target element. Remember thatidmatching is case-sensitive —helpTextandhelptextare 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-describedbyattribute entirely rather than leaving a broken reference. - Verify all IDs in a multi-value list. If
aria-describedbycontains 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">
The aria-errormessage attribute is not allowed on a <label> element when that <label> contains a labelable element (such as <input>, <select>, <textarea>, or <button>).
aria-errormessage identifies the element that holds the error text for a control whose value is invalid. It belongs on the control itself, alongside aria-invalid="true", and its value is the id of the element containing the message. A <label> has no validity state, so the attribute has nothing to describe there.
When the <label> wraps a labelable element, the control inside it is the thing that can be valid or invalid. Putting aria-errormessage on the surrounding <label> points assistive technology at an error for an element that cannot have one, which is why the spec rejects it. A "labelable element" is any element a <label> can be associated with: <input> (except type="hidden"), <select>, <textarea>, <button>, <meter>, <output>, and <progress>.
Move aria-errormessage to the form control, and pair it with aria-invalid so the message is announced only while the value is invalid.
Examples
Invalid: aria-errormessage on a label that wraps an input
<label aria-errormessage="email-error">
<input type="email" name="email">
</label>
<span id="email-error">Enter a valid email address.</span>
Fixed: move it to the input, with aria-invalid
<label>
<input type="email" name="email" aria-invalid="true" aria-errormessage="email-error">
</label>
<span id="email-error">Enter a valid email address.</span>
The aria-errormessage attribute is not allowed on a <label> element that points to a form control through its for attribute.
aria-errormessage takes the id of the element holding the error text for a form control. Assistive technology announces that text when the control is marked invalid with aria-invalid="true". Both attributes describe the control's value, so both go on the control.
A <label> with a for attribute is associated with the labelable element whose id matches, and its text becomes that element's accessible name. The label has no value and no validity state of its own, so an error reference on it has nothing to describe. The control it names still has no error message attached, and a screen reader user who reaches the invalid field hears no error.
Move aria-errormessage from the <label> to the control named in for, and set aria-invalid="true" on the control while its value fails validation. If the <label> wraps the control instead of using for, the validator reports the same mistake with a different message, saying the <label> is an ancestor of a labelable element.
Invalid example
<input type="checkbox" id="terms" name="terms" required>
<label for="terms" aria-errormessage="terms-error">I accept the terms of service</label>
<span id="terms-error">You must accept the terms to continue.</span>
Valid example
<input type="checkbox" id="terms" name="terms" required aria-invalid="true" aria-errormessage="terms-error">
<label for="terms">I accept the terms of service</label>
<span id="terms-error">You must accept the terms to continue.</span>
A <label> whose for attribute points at a form control can't carry aria-expanded, because the label only names that control and has no open or closed state to report.
aria-expanded tells assistive technologies whether the content a control shows and hides, such as a dropdown menu or an accordion panel, is open right now. Screen readers read it out when the control gets focus, as in "Menu, button, collapsed". ARIA permits it on interactive roles like button, checkbox, combobox, link and tab.
Assistive technologies don't expose a <label> linked by for as an element in its own right. They read its text as the control's accessible name, and focus goes to the control, so a state set on the label is never announced. A <label> that wraps its control instead of using for gets a separate message, about a label that is an ancestor of a labelable element. The fix is the same.
The message usually comes from a CSS-only toggle: a hidden checkbox opens a mobile menu, or hidden radio buttons switch slides or tabs, and the <label> is styled as the button. CSS can't change attributes, so a hard-coded aria-expanded="false" stays false after the menu opens. Moving it onto the checkbox clears the error but leaves the value just as stale. Use a <button type="button"> with aria-expanded and aria-controls instead, with a short script that flips the value and shows or hides the content. If you'd rather avoid script, <details> and <summary> report their open state to assistive technologies with no ARIA at all.
For a slider or tabs built from radio buttons, remove aria-expanded. The checked radio already tells screen readers which slide is selected, and the validator rejects aria-expanded on <input type="radio"> unless the input also has a role.
Invalid example
<nav>
<input type="checkbox" id="menu-toggle" class="menu-toggle">
<label for="menu-toggle" aria-expanded="false">Menu</label>
<ul class="menu">
<li><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
</ul>
</nav>
Valid example
<nav>
<button type="button" id="menu-button" aria-expanded="false" aria-controls="main-menu">
Menu
</button>
<ul id="main-menu" hidden>
<li><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
</ul>
</nav>
<script>
const button = document.getElementById("menu-button");
const menu = document.getElementById("main-menu");
button.addEventListener("click", () => {
const open = button.getAttribute("aria-expanded") === "true";
button.setAttribute("aria-expanded", String(!open));
menu.hidden = open;
});
</script>
The aria-expanded attribute is redundant on a summary element when it is the direct child of a details element, because the browser already communicates the expanded/collapsed state through the native open attribute on details.
The summary element, when used as the first child of a details element, acts as the built-in toggle control. Assistive technologies already understand this relationship and automatically convey whether the disclosure widget is open or closed based on the details element's open attribute. Adding aria-expanded to summary in this context creates duplicate semantics, which can confuse screen readers by announcing the state twice.
If you're using JavaScript to toggle aria-expanded manually, you can safely remove it and rely on the native behavior instead. The details/summary pattern is one of the best examples of built-in accessibility that requires no extra ARIA attributes.
Incorrect Example
<details>
<summary aria-expanded="false">More information</summary>
<p>Here are the additional details.</p>
</details>
Correct Example
<details>
<summary>More information</summary>
<p>Here are the additional details.</p>
</details>
If you need the section to be open by default, use the open attribute on the details element:
<details open>
<summary>More information</summary>
<p>Here are the additional details.</p>
</details>
The aria-haspopup attribute belongs on the menu item that opens a submenu, not on the role="menubar" element that holds the items.
aria-haspopup tells screen readers that activating an element opens a popup, such as a menu or a dialog. A menu bar doesn't open anything. It stays on screen, and users activate the items inside it. WAI-ARIA 1.2 deprecated aria-haspopup as a global property and lists the roles that support it: application, button, combobox, gridcell, link, menuitem, slider, tab, textbox and treeitem, plus the roles that inherit from them. menubar isn't on that list, so assistive technology can ignore the attribute there, and users can't tell which item has a submenu.
The validator flags any element with an explicit role="menubar" and an aria-haspopup attribute, whatever its value, so aria-haspopup="false" triggers the warning too. If the element is a real menu bar, move aria-haspopup="menu" to each menuitem that opens a submenu, and add aria-expanded there to say whether that submenu is open.
Sometimes the element isn't a menu bar at all. It's a control that shows a dropdown, like a language picker or a mobile navigation toggle. Drop role="menubar" there and use a <button> with aria-expanded and aria-controls, as the disclosure pattern describes. The links inside the panel stay plain links.
Invalid example
<ul role="menubar" aria-label="Editor" aria-haspopup="menu">
<li role="none">
<button type="button" role="menuitem" aria-expanded="false" aria-controls="file-menu">File</button>
<ul role="menu" id="file-menu" aria-label="File" hidden>
<li role="menuitem" tabindex="-1">New</li>
<li role="menuitem" tabindex="-1">Open</li>
</ul>
</li>
<li role="none">
<button type="button" role="menuitem" tabindex="-1">Help</button>
</li>
</ul>
Valid example
The menu item that opens the submenu carries aria-haspopup:
<ul role="menubar" aria-label="Editor">
<li role="none">
<button type="button" role="menuitem" aria-haspopup="menu" aria-expanded="false" aria-controls="file-menu">File</button>
<ul role="menu" id="file-menu" aria-label="File" hidden>
<li role="menuitem" tabindex="-1">New</li>
<li role="menuitem" tabindex="-1">Open</li>
</ul>
</li>
<li role="none">
<button type="button" role="menuitem" tabindex="-1">Help</button>
</li>
</ul>
A dropdown of links, such as a language picker, uses a disclosure button instead of menu roles:
<button type="button" aria-expanded="false" aria-controls="language-list">Language</button>
<ul id="language-list" hidden>
<li><a href="/" hreflang="en">English</a></li>
<li><a href="/es/" hreflang="es" lang="es">Español</a></li>
</ul>
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:
<form action="/submit" method="post">
<input type="hidden" aria-hidden="true" name="month" value="10">
<input type="hidden" aria-hidden="true" name="csrf_token" value="abc123">
<button type="submit">Submit</button>
</form>
Correct
Remove the aria-hidden attribute entirely. The hidden inputs are already inaccessible to all users by default:
<form action="/submit" method="post">
<input type="hidden" name="month" value="10">
<input type="hidden" name="csrf_token" value="abc123">
<button type="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:
<button type="button">
<span aria-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 <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
<link rel="stylesheet" href="styles.css" aria-hidden="true">
<link rel="icon" href="favicon.ico" aria-hidden="true">
<link rel="preload" href="font.woff2" as="font" type="font/woff2" aria-hidden="true">
Correct: <link> without aria-hidden
<link rel="stylesheet" href="styles.css">
<link rel="icon" href="favicon.ico">
<link rel="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:
<link rel="stylesheet" href="styles.css">
<div aria-hidden="true">
<img src="decorative-swirl.png" alt="">
</div>
Incorrect vs. correct in a full document
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My Page</title>
<!-- Incorrect: aria-hidden on link -->
<link rel="stylesheet" href="styles.css" aria-hidden="true">
</head>
<body>
<p>Hello, world!</p>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My Page</title>
<!-- Correct: no aria-hidden on link -->
<link rel="stylesheet" href="styles.css">
</head>
<body>
<p>Hello, world!</p>
</body>
</html>
Validate at scale.
Ship accessible websites, faster.
Automated HTML & accessibility validation for large sites. Check thousands of pages against WCAG guidelines and W3C standards in minutes, not days.
1K Weekly
1,000 monthly checks. Cancel anytime.
Get 1K Weekly →Join teams across 40+ countries