HTML Guides for role
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.
The role attribute lists more than one ARIA role, and browsers use only the first one they recognize.
The value of role is a list of tokens separated by spaces. WAI-ARIA allows the list as a fallback mechanism: the browser reads the tokens from left to right and uses the first one that names a defined, non-abstract ARIA role. Every token after that one is ignored. The validator names the ignored token in the message. When there are several, it lists them all in a single message.
A repeated role, such as role="region region", is the most common cause. Page builders and templates produce it when two pieces of code each add the same role to one element. The browser treats it exactly like role="region", so deleting the copy changes nothing for screen reader users. For this particular role you can also use a <section> with an accessible name, which has the region role without any role attribute.
The other cause is a fallback list written on purpose, such as role="switch checkbox", meant for browsers that don't support the first role. A browser that knows switch never reads checkbox. Keep the one role that describes what the element does and remove the rest. If two different roles both seem to fit, the element is probably doing two jobs, and it's better to split it into two elements.
When the first token isn't a valid role, the validator reports it with a different message, "Discarding unrecognized token", and browsers move on to the next token in the list.
Invalid example
<div role="region region" aria-labelledby="faq-heading">
<h2 id="faq-heading">Frequently asked questions</h2>
<p>Answers to common questions about shipping and returns.</p>
</div>
<button type="button" role="switch checkbox" aria-checked="false">Dark mode</button>
Valid example
<div role="region" aria-labelledby="faq-heading">
<h2 id="faq-heading">Frequently asked questions</h2>
<p>Answers to common questions about shipping and returns.</p>
</div>
<button type="button" role="switch" aria-checked="false">Dark mode</button>
The role attribute contains a token that does not name a defined, non-abstract ARIA role.
A role value can contain a list of tokens separated by spaces. Browsers read the list from left to right and use the first recognized, non-abstract role. They ignore unknown tokens such as initial. Although initial is a CSS keyword, it does not reset an ARIA role.
Remove the unrecognized token and keep the role that describes the element's purpose. In this example, status identifies a message that assistive technologies can announce when it changes. Removing initial preserves that role. If a native HTML element already provides the intended semantics, use it without an unnecessary role attribute.
Invalid example
<div role="initial status">Application received.</div>
Valid example
<div role="status">Application received.</div>
An <a> element without an href attribute can't use aria-expanded unless it also has a role that supports that state.
Without href, an <a> isn't a link. HTML treats it as a placeholder, and its ARIA role is generic. The aria-expanded attribute only applies to certain roles, such as button, link, tab and menuitem, so on a placeholder anchor it describes a state that screen readers have nothing to attach to. The anchor also can't receive keyboard focus, so keyboard users can't reach the control.
This usually comes from a menu or dropdown toggle written as <a aria-expanded="false"> and wired up with JavaScript. The message also lists aria-checked and aria-level, but adding either of them doesn't fix the element: the validator then asks for href or role instead. Add an href if the element takes the user somewhere. If it opens and closes part of the page, replace it with a <button type="button">, which is focusable, works with the keyboard and supports aria-expanded without extra attributes. Keeping the <a> with role="button" and tabindex="0" also passes validation, but then your script has to handle the Enter and Space keys.
Invalid example
<a class="menu-toggle" aria-expanded="false" aria-controls="account-menu">Account</a>
<ul id="account-menu" hidden>
<li><a href="/profile">Profile</a></li>
<li><a href="/logout">Log out</a></li>
</ul>
Valid example
<button type="button" class="menu-toggle" aria-expanded="false" aria-controls="account-menu">Account</button>
<ul id="account-menu" hidden>
<li><a href="/profile">Profile</a></li>
<li><a href="/logout">Log out</a></li>
</ul>
An <a> element without an href attribute can't use aria-selected unless it also has a role that supports the selected state.
Only four roles support aria-selected: tab, option, row and gridcell. An <a> with an href has the link role, and one without href is a placeholder with the generic role. Neither has a selected state, so the attribute tells assistive technology nothing it can use. An anchor without href also can't receive keyboard focus, which leaves keyboard users unable to reach it.
The error usually comes from tabs or filter buttons built from bare <a> tags, where a script moves aria-selected="true" to the active item. The message also lists aria-checked and href, but adding either one only swaps this error for another: links don't support aria-selected, and aria-checked doesn't stand in for the missing role.
For tabs, give each tab role="tab", wrap the group in a role="tablist" container and point each tab at its role="tabpanel" with aria-controls. A <button type="button"> works better than an <a> here because it's focusable without a tabindex. If the control shows and hides content, use a <button> with aria-expanded. If it marks the current page in a navigation menu, give the link its href and use aria-current="page" instead.
Invalid example
<div class="tabs">
<a aria-selected="true" aria-controls="panel-specs">Specifications</a>
<a aria-selected="false" aria-controls="panel-reviews">Reviews</a>
</div>
<div id="panel-specs">
<p>Weight: 1.2 kg</p>
</div>
<div id="panel-reviews" hidden>
<p>No reviews yet.</p>
</div>
Valid example
<div role="tablist" aria-label="Product details">
<button type="button" role="tab" id="tab-specs" aria-selected="true" aria-controls="panel-specs">Specifications</button>
<button type="button" role="tab" id="tab-reviews" aria-selected="false" aria-controls="panel-reviews" tabindex="-1">Reviews</button>
</div>
<div role="tabpanel" id="panel-specs" aria-labelledby="tab-specs">
<p>Weight: 1.2 kg</p>
</div>
<div role="tabpanel" id="panel-reviews" aria-labelledby="tab-reviews" hidden>
<p>No reviews yet.</p>
</div>
A link (an <a> with an href) has an aria-selected attribute but no role that supports it.
aria-selected only means something on roles such as tab, option, row and gridcell. A link has the link role, which has no selected state, so the attribute has no defined meaning there. The message lists aria-checked next to role, but role is the one that matters: adding aria-checked only changes the error to one that asks for role. Without an href, the message also asks for href.
Often aria-selected is there to mark the current page in a navigation menu. That job belongs to aria-current="page", which works on plain links and needs no role. Put it on the link to the page the user is on, and leave it off the others.
If the links really are tabs that switch between panels on the same page, give each one role="tab", put them inside an element with role="tablist", and point each tab at a role="tabpanel" element. The validator checks those parts too. Tabs also need scripted keyboard support, as the WAI-ARIA tabs pattern describes.
Invalid example
<nav aria-label="Main">
<ul>
<li><a href="/" aria-selected="true">Home</a></li>
<li><a href="/blog/" aria-selected="false">Blog</a></li>
</ul>
</nav>
Valid example
Navigation links mark the current page with aria-current:
<nav aria-label="Main">
<ul>
<li><a href="/" aria-current="page">Home</a></li>
<li><a href="/blog/">Blog</a></li>
</ul>
</nav>
Links that work as tabs get the tab roles:
<div role="tablist" aria-label="Account">
<a href="#profile" role="tab" id="tab-profile" aria-controls="profile" aria-selected="true">Profile</a>
<a href="#billing" role="tab" id="tab-billing" aria-controls="billing" aria-selected="false" tabindex="-1">Billing</a>
</div>
<div id="profile" role="tabpanel" aria-labelledby="tab-profile">Profile settings</div>
<div id="billing" role="tabpanel" aria-labelledby="tab-billing" hidden>Billing settings</div>
According to the HTML specification, the <a> element can exist without an href attribute, but in that case it represents a placeholder where a link might otherwise have been placed. However, the validator flags this as an issue because an <a> element without href and without role is ambiguous — browsers won't treat it as a link (it won't be focusable or keyboard-accessible), and assistive technologies won't know how to present it to users.
This matters for several reasons:
- Accessibility: Without
href, the<a>element loses its implicitrole="link"and is no longer announced as a link by screen readers. It also won't appear in the tab order, making it invisible to keyboard users. - Semantics: If the element is styled and scripted to behave like a button or link but lacks the proper attributes, it creates a disconnect between what users see and what the browser understands.
- Standards compliance: The spec expects you to be explicit about the element's purpose when
hrefis absent.
The most common cause of this issue is using <a> elements as JavaScript-only click targets without providing an href, or using them as styled containers without any interactive purpose.
How to Fix It
There are several approaches depending on your intent:
- Add an
hrefattribute if the element should be a link. This is the most common and recommended fix. - Add a
roleattribute if you're deliberately using<a>withouthreffor a specific purpose, such asrole="button". - Use a different element entirely. If it's not a link, consider using a
<button>,<span>, or another semantically appropriate element.
Examples
❌ Missing both href and role
<a>Click here</a>
This triggers the validator error because the <a> has neither href nor role.
❌ JavaScript-only handler without href
<a onclick="doSomething()">Submit</a>
Even with an event handler, the element lacks href and role, so it fails validation and is inaccessible to keyboard users.
✅ Fix by adding an href
<a href="/about">About us</a>
Adding href makes it a proper hyperlink — focusable, keyboard-accessible, and recognized by screen readers.
✅ Fix by adding role for a non-link purpose
<a role="button" tabindex="0" onclick="doSomething()">Submit</a>
If you must use <a> without href as a button, add role="button" and tabindex="0" to ensure it's focusable and properly announced. However, consider using a real <button> instead.
✅ Better: use the right element
<button type="button" onclick="doSomething()">Submit</button>
If the element triggers an action rather than navigating somewhere, a <button> is the correct semantic choice. It's focusable by default, responds to keyboard events, and doesn't need extra attributes.
✅ Placeholder anchor (intentional non-link)
<a role="link" aria-disabled="true">Coming soon</a>
If you're intentionally showing a placeholder where a link will eventually appear, you can add a role and indicate its disabled state for assistive technologies. Alternatively, use a <span> with appropriate styling to avoid the issue altogether.
The HTML specification defines <button> as a versatile interactive element, but its behavior changes depending on context. When a <button> is placed inside a <form> without a type attribute, it defaults to type="submit", which can cause unexpected form submissions. The validator flags this because relying on the implicit default is ambiguous and error-prone. Explicitly setting the type attribute makes the button's intent clear to both developers and browsers.
The three valid values for the type attribute are:
submit— submits the parent form's data to the server.reset— resets all form controls to their initial values.button— performs no default action; behavior is defined via JavaScript.
When a <button> is given an ARIA role of checkbox, switch, or menuitemcheckbox, the validator expects an aria-checked attribute to accompany it. These roles describe toggle controls that have a checked or unchecked state, so assistive technologies need to know the current state. Without aria-checked, screen readers cannot communicate whether the control is on or off, making the interface inaccessible.
The aria-checked attribute accepts the following values:
true— the control is checked or on.false— the control is unchecked or off.mixed— the control is in an indeterminate state (valid forcheckboxandmenuitemcheckboxroles only).
How to fix it
For standard buttons, add the type attribute with the appropriate value. If the button triggers JavaScript behavior and is not meant to submit a form, use type="button". If it submits a form, use type="submit" explicitly to make the intent clear.
For toggle buttons, ensure the <button> has both a role attribute (such as checkbox or switch) and an aria-checked attribute that reflects the current state. You should also include type="button" to prevent unintended form submission. Use JavaScript to toggle the aria-checked value when the user interacts with the button.
Examples
Missing type attribute
This triggers the validator warning because the type is not specified:
<form action="/search">
<input type="text" name="q">
<button>Search</button>
</form>
Fixed by adding an explicit type:
<form action="/search">
<input type="text" name="q">
<button type="submit">Search</button>
</form>
Button used outside a form without type
<button onclick="openMenu()">Menu</button>
Fixed by specifying type="button":
<button type="button" onclick="openMenu()">Menu</button>
Toggle button missing aria-checked
A button with role="switch" but no aria-checked attribute:
<button type="button" role="switch">Dark Mode</button>
Fixed by adding aria-checked:
<button type="button" role="switch" aria-checked="false">Dark Mode</button>
Checkbox-style toggle button
A button acting as a checkbox must include both role="checkbox" and aria-checked:
<button type="button" role="checkbox" aria-checked="false">
Enable notifications
</button>
Complete toggle example with all required attributes
<button type="button" role="switch" aria-checked="false" id="wifi-toggle">
Wi-Fi
</button>
<script>
document.getElementById("wifi-toggle").addEventListener("click", function () {
const isChecked = this.getAttribute("aria-checked") === "true";
this.setAttribute("aria-checked", String(!isChecked));
});
</script>
In this example, the type="button" prevents form submission, the role="switch" tells assistive technologies this is a toggle, and aria-checked is updated dynamically to reflect the current state. This ensures the button is fully accessible and passes validation.
The aria-expanded attribute cannot be used on a plain div element without also specifying a role attribute.
The aria-expanded attribute indicates whether a grouping of content that the element owns or controls is currently expanded or collapsed. However, this attribute is only valid on elements that have an appropriate implicit or explicit role. A plain div has no implicit ARIA role, so you must assign one explicitly.
The aria-expanded attribute is commonly used with interactive roles such as button, combobox, treeitem, or link. Adding the correct role tells assistive technologies what kind of element the user is interacting with, making aria-expanded meaningful in context.
HTML Examples
❌ Invalid: aria-expanded on a plain div
<div aria-expanded="false">
Menu content
</div>
✅ Valid: aria-expanded with an appropriate role
<div role="button" aria-expanded="false">
Menu content
</div>
Alternatively, consider using a native HTML element that already carries the correct semantics, which avoids the need for a role attribute entirely:
<button aria-expanded="false">
Toggle Menu
</button>
Using a native <button> is generally preferred over <div role="button"> because it comes with built-in keyboard interaction and focus behavior.
The aria-required attribute tells assistive technologies that a form field must be filled in before the form can be submitted. However, this attribute is only valid on elements that function as interactive widgets. A bare div has no implicit ARIA role, so assistive technologies have no context for what kind of input is expected. The validator flags this because an aria-required attribute on a generic div is effectively meaningless without additional ARIA attributes that define the element's role and behavior.
This matters for several reasons:
- Accessibility: Screen readers and other assistive technologies rely on roles to understand how to present an element to users. Without a role,
aria-requiredprovides incomplete information. - Standards compliance: The WAI-ARIA specification defines which attributes are allowed on which roles. Using
aria-requiredwithout an established role violates these constraints. - Browser behavior: Browsers may ignore or misinterpret ARIA attributes when they appear on elements that lack the proper role context.
How to fix it
Option 1: Use native semantic HTML (preferred)
Whenever possible, use native HTML form elements. They come with built-in accessibility semantics, keyboard interaction, and validation — no ARIA needed.
Replace a div with aria-required="true" with an appropriate form control using the native required attribute:
<input type="text" required>
<select required>
<option value="">Choose one</option>
<option value="1">Option 1</option>
</select>
<textarea required></textarea>
Option 2: Add an appropriate role attribute
When you must use a div as a custom widget (styled and enhanced with CSS and JavaScript), add the correct role attribute to give it semantic meaning. Choose the role that matches the widget's actual behavior — don't just pick one arbitrarily.
Common roles that support aria-required:
combobox— a custom dropdown with text inputlistbox— a custom selection listradiogroup— a group of radio-like optionsspinbutton— a numeric stepper (also requiresaria-valuemax,aria-valuemin, andaria-valuenow)textbox— a custom text input
Option 3: Add other qualifying ARIA attributes
For certain widgets like sliders or spinbuttons, you may need aria-valuemax, aria-valuemin, and aria-valuenow in addition to (or as part of) defining the role. These attributes inherently establish a widget context.
Examples
❌ Invalid: aria-required on a plain div
<div aria-required="true">
<div data-value="One">1</div>
<div data-value="Two">2</div>
<div data-value="Three">3</div>
</div>
This triggers the validation error because the div has no role or other ARIA attributes to define what kind of widget it is.
✅ Fixed: Adding the appropriate role
<div aria-required="true" role="radiogroup" aria-label="Pick a number">
<div role="radio" aria-checked="false" tabindex="0">1</div>
<div role="radio" aria-checked="false" tabindex="0">2</div>
<div role="radio" aria-checked="false" tabindex="0">3</div>
</div>
Adding role="radiogroup" gives the div a semantic identity. Note that child elements also need appropriate roles and attributes for the widget to be fully accessible.
✅ Fixed: Using native HTML instead
<fieldset>
<legend>Pick a number</legend>
<label><input type="radio" name="number" value="1" required> 1</label>
<label><input type="radio" name="number" value="2"> 2</label>
<label><input type="radio" name="number" value="3"> 3</label>
</fieldset>
This approach uses native radio buttons with the required attribute, eliminating the need for ARIA entirely. The browser handles accessibility, keyboard navigation, and form validation automatically.
✅ Fixed: A custom spinbutton with value attributes
<div role="spinbutton"
aria-required="true"
aria-valuemin="0"
aria-valuemax="100"
aria-valuenow="50"
aria-label="Quantity"
tabindex="0">
50
</div>
For a spinbutton role, you must also provide aria-valuemin, aria-valuemax, and aria-valuenow to fully describe the widget's state.
A <label> can't carry aria-expanded unless it also has a role, and the validator reports this message when it finds one that doesn't.
aria-expanded tells assistive technologies whether a control's collapsible content, such as an accordion panel or a menu, is open or closed. ARIA allows it only on interactive roles like button, combobox, link or tab. A <label> has no ARIA role of its own, since its only job is to name a form control. The message lists three attributes, but only role clears it. Add aria-checked or aria-level and the validator asks for role instead.
The message usually comes from an accordion whose clickable header is a <label>, often with aria-controls pointing at the panel and a script that toggles it. Keyboard users can't reach that header, because a <label> doesn't take focus, and screen readers don't announce it as something to press. Make the header a <button type="button"> and move aria-expanded and aria-controls onto it. If the section has a title, put the button inside a heading. A <button> has no for attribute, so drop it. For a simple disclosure that needs no script, <details> and <summary> track the open state without any ARIA.
Adding role="button" and tabindex="0" to the <label> also clears the message. You then have to handle the Enter and Space keys in script, though, and a <label> linked to a form control keeps forwarding its clicks to that control. That link causes a second error too: the validator reports that aria-expanded and aria-controls must not be used on a <label> associated with a form control. A <label> that wraps its control gets a similar message about a label that is an ancestor of a labelable element.
Invalid example
<label id="shipping-header" aria-expanded="false" aria-controls="shipping-panel">
Shipping
</label>
<div id="shipping-panel" role="region" aria-labelledby="shipping-header" hidden>
<p>Orders ship within two business days.</p>
</div>
Valid example
<h2>
<button type="button" id="shipping-header" aria-expanded="false" aria-controls="shipping-panel">
Shipping
</button>
</h2>
<div id="shipping-panel" role="region" aria-labelledby="shipping-header" hidden>
<p>Orders ship within two business days.</p>
</div>
A <p> element has an aria-expanded attribute, but a paragraph has no role that supports it.
aria-expanded tells assistive technologies whether the content an element controls, such as an accordion panel or a menu, is shown or hidden. ARIA allows it on roles like button, link, combobox, tab and treeitem. A <p> has the paragraph role, which has no expanded state, so the attribute means nothing there. The message lists three attributes, but only role clears it. Add aria-checked or aria-level and the validator asks for role alone.
The attribute often ends up on the paragraph that holds a toggle's text, or on the content a script opens and closes. If the paragraph doesn't show or hide anything, delete the attribute. If clicking it does, put a <button type="button"> inside the paragraph and move aria-expanded and aria-controls onto the button. Keyboard users can't reach a clickable <p>, because it doesn't take focus, and screen readers don't announce it as something to press.
Adding role="button" and tabindex="0" to the <p> also clears the message, but then the Enter and Space keys have to be handled in script. A <button> gets focus and keyboard activation without any script.
Invalid example
<p aria-expanded="false" aria-controls="hours">Opening hours</p>
<div id="hours" hidden>
<p>Monday to Friday, 9:00 to 17:00.</p>
</div>
Valid example
<p>
<button type="button" aria-expanded="false" aria-controls="hours">Opening hours</button>
</p>
<div id="hours" hidden>
<p>Monday to Friday, 9:00 to 17:00.</p>
</div>
The aria-expanded attribute requires the element to have an appropriate role attribute (or be an element that natively implies one). A <span> is a generic inline element with no implicit ARIA role, so you must explicitly assign a role when using ARIA state attributes like aria-expanded.
The aria-expanded attribute indicates whether a grouping element controlled by this element is currently expanded or collapsed. It is only valid on elements with specific roles such as button, link, combobox, menuitem, or other widget roles. When a <span> uses aria-expanded without a role, validators flag it because there's no semantic context for that state.
Since this element toggles a dropdown menu and has aria-label, aria-controls, and aria-expanded, the most appropriate role is button. This tells assistive technologies that the element is interactive and can be activated.
Also note that when using role="button" on a non-interactive element like <span>, you should ensure it is focusable by adding tabindex="0" and that it handles keyboard events (Enter and Space keys).
HTML Examples
❌ Invalid: aria-expanded on a span without a role
<span class="navbar-dropdown-icon"
aria-expanded="false"
aria-label="List options"
aria-controls="dropdown-menu-item-1-1menu-item-2-6"
data-toggle="dropdown">
</span>
✅ Valid: adding role="button" and tabindex="0"
<span class="navbar-dropdown-icon"
role="button"
tabindex="0"
aria-expanded="false"
aria-label="List options"
aria-controls="dropdown-menu-item-1-1menu-item-2-6"
data-toggle="dropdown">
</span>
✅ Better: use a <button> element instead
<button class="navbar-dropdown-icon"
type="button"
aria-expanded="false"
aria-label="List options"
aria-controls="dropdown-menu-item-1-1menu-item-2-6"
data-toggle="dropdown">
</button>
Using a native <button> is preferred because it is focusable and keyboard-accessible by default, without needing role or tabindex.
The span element is a generic inline container with no inherent semantics. On its own, it carries no meaning for assistive technologies. When you add ARIA attributes like aria-expanded or aria-valuenow to a span, you are signaling that the element represents an interactive widget — but the validator (and assistive technologies) need more context. Many ARIA attributes are only permitted on elements that have certain roles, and some roles require a specific set of attributes to function correctly.
For example, aria-valuenow is designed for range widgets like sliders and progress bars. According to the WAI-ARIA specification, if you use aria-valuenow, the element must also have aria-valuemin, aria-valuemax, and a role such as progressbar, slider, meter, or scrollbar. Similarly, aria-expanded is meant for elements with roles like button, combobox, link, or treeitem. Placing these attributes on a bare span without the corresponding role violates the ARIA rules and triggers this validation error.
This matters for several reasons:
- Accessibility: Screen readers rely on the
roleto determine how to present a widget to users. Without it, ARIA state attributes become meaningless or confusing. - Standards compliance: The HTML specification integrates ARIA rules, and validators enforce that ARIA attributes are used in valid combinations.
- Browser behavior: Browsers use the
roleto build the accessibility tree. Aspanwitharia-valuenowbut norolemay be ignored or misrepresented to assistive technology users.
How to fix it
- Add the correct
roleto thespan, along with all attributes required by that role. - Use a semantic HTML element instead of a
spanwhen one exists (e.g.,<progress>or<button>). - Remove unnecessary ARIA attributes if the
spanis purely decorative or the attributes were added by mistake.
If your span is purely visual (e.g., a decorative asterisk for required fields), don't add state-related ARIA attributes to it. Instead, use aria-hidden="true" to hide it from assistive technologies, and place ARIA attributes on the actual form control.
Examples
Incorrect: aria-expanded on a span without a role
<span aria-expanded="false">Menu</span>
The validator reports the missing role because aria-expanded isn't valid on a generic span.
Correct: Add a role (or use a button)
<span role="button" tabindex="0" aria-expanded="false">Menu</span>
Or, better yet, use a real button element:
<button aria-expanded="false">Menu</button>
Incorrect: aria-valuenow without the full set of range attributes and role
<span class="progress-indicator" aria-valuenow="50">50%</span>
Correct: Include the role and all required range attributes
<span role="progressbar" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">
50%
</span>
Or use the native <progress> element, which has built-in semantics:
<progress value="50" max="100">50%</progress>
Incorrect: aria-required on a decorative span
<label for="email">
<span class="required" aria-required="true">*</span>
</label>
<input id="email" name="email" type="email">
The aria-required attribute belongs on the form control, not on the decorative asterisk.
Correct: Hide the decorative indicator and mark the input as required
<label for="email">
<span class="required" aria-hidden="true">*</span>
</label>
<input id="email" name="email" type="email" aria-required="true">
If you also want screen readers to announce "required" as part of the label text, add visually hidden text:
<label for="email">
<span aria-hidden="true">*</span>
<span class="visually-hidden">required</span>
</label>
<input id="email" name="email" type="email" required>
The key takeaway: whenever you use ARIA state or property attributes on a span, make sure the element also has the correct role and all companion attributes required by that role. When a native HTML element already provides the semantics you need — such as <button>, <progress>, or <meter> — prefer it over a span with ARIA, as native elements are more robust and require less additional markup.
The summary element needs an explicit role attribute when the W3C validator detects it's being used in a context where its implicit ARIA semantics are unclear or overridden.
The summary element is designed to be used as the first child of a <details> element, where it acts as a clickable disclosure toggle. When used correctly inside <details>, it has an implicit ARIA role and doesn't need additional attributes.
This validation warning typically appears when:
- The
summaryelement is used outside of a<details>element. - The
summaryelement has an explicitroleattribute that requires additional ARIA properties (e.g.,role="checkbox"requiresaria-checked, orrole="heading"requiresaria-level).
The simplest fix is to ensure summary is used correctly as a direct child of <details>, and to remove any unnecessary or conflicting role attributes.
Example with the issue
<!-- summary outside of details triggers the warning -->
<summary>Click to expand</summary>
<p>Some content here.</p>
<!-- Or summary with an incomplete role override -->
<details>
<summary role="heading">Section Title</summary>
<p>Some content here.</p>
</details>
How to fix it
<!-- Use summary correctly inside details -->
<details>
<summary>Click to expand</summary>
<p>Some content here.</p>
</details>
<!-- If you need a heading role, include the required aria-level -->
<details>
<summary role="heading" aria-level="3">Section Title</summary>
<p>Some content here.</p>
</details>
If you don't have a specific reason to override the role, simply remove the role attribute and let the summary element keep its native semantics within <details>.
The aria-checked attribute communicates the checked state of an interactive widget to assistive technologies. According to the WAI-ARIA specification, this attribute is only permitted on elements that have a role supporting the "checked" state — such as checkbox, switch, radio, menuitemcheckbox, or menuitemradio. A plain <td> element has an implicit role of cell (or gridcell when inside a role="grid" table), neither of which supports aria-checked. When the validator encounters aria-checked on a <td> without a compatible role, it flags the element as invalid.
This matters for several reasons:
- Accessibility: Screen readers and other assistive technologies rely on the relationship between
roleand ARIA state attributes. Anaria-checkedon an element without a recognized checkable role creates a confusing or broken experience — users may not understand that the cell is supposed to be interactive. - Standards compliance: The ARIA in HTML specification defines strict rules about which attributes are allowed on which roles. Violating these rules means your HTML is technically invalid.
- Browser behavior: Browsers may ignore
aria-checkedentirely when it's used on an element without a valid role, making the attribute useless.
How to fix it
You have two main approaches depending on what your <td> is meant to do:
1. Add an appropriate role attribute. If the table cell genuinely represents a checkable control (for example, in an interactive data grid), add role="checkbox", role="switch", or another appropriate checkable role to the <td>, along with tabindex for keyboard accessibility.
2. Remove aria-checked and use a real control. If the cell simply contains a checkbox or toggle, place an actual <input type="checkbox"> inside the <td> and remove the ARIA attributes from the cell itself. Native HTML controls already communicate their state to assistive technologies without extra ARIA.
Examples
❌ Incorrect: aria-checked without a role
<table>
<tr>
<td aria-checked="true">Selected</td>
<td>Item A</td>
</tr>
</table>
This triggers the error because <td> has the implicit role of cell, which does not support aria-checked.
✅ Fix: Add a compatible role to the <td>
<table role="grid">
<tr>
<td role="checkbox" aria-checked="true" tabindex="0">Selected</td>
<td>Item A</td>
</tr>
</table>
Here the <td> explicitly has role="checkbox", which supports aria-checked. The tabindex="0" makes it keyboard-focusable, and role="grid" on the table signals that cells may be interactive.
✅ Fix: Use a native checkbox inside the <td>
<table>
<tr>
<td>
<label>
<input type="checkbox" checked>
Selected
</label>
</td>
<td>Item A</td>
</tr>
</table>
This approach is often the best option. The native <input type="checkbox"> already conveys its checked state to assistive technologies, and no ARIA attributes are needed on the <td>.
❌ Incorrect: Mismatched role and aria-checked
<table>
<tr>
<td role="button" aria-checked="false">Toggle</td>
<td>Item B</td>
</tr>
</table>
The button role does not support aria-checked. This would trigger a different but related validation error.
✅ Fix: Use a role that supports aria-checked
<table role="grid">
<tr>
<td role="switch" aria-checked="false" tabindex="0">Toggle</td>
<td>Item B</td>
</tr>
</table>
The switch role supports aria-checked and is appropriate for toggle-style controls.
ARIA (Accessible Rich Internet Applications) works as a system where roles define what an element is, and states and properties describe the element's current condition or characteristics. Certain ARIA attributes are only valid when used on elements that have a specific role — either explicitly declared via the role attribute or implicitly provided by the HTML element itself. When you add an ARIA state or property to a generic element like a <div> or <span> without specifying a role, assistive technologies have no context for interpreting that attribute. For example, aria-expanded="true" on a plain <div> tells a screen reader that something is expanded, but it doesn't communicate what is expanded — is it a button, a navigation menu, a tree item? The role provides that crucial context.
This matters for several reasons:
- Accessibility: Screen readers and other assistive technologies rely on the combination of roles and their associated states/properties to convey meaningful information to users. An ARIA property without a role is ambiguous and can lead to a confusing experience.
- Standards compliance: The WAI-ARIA specification defines which states and properties are allowed on which roles. Using an ARIA attribute outside of a valid role context violates the spec.
- Predictable behavior: Browsers and assistive technologies may handle orphaned ARIA attributes inconsistently, leading to unpredictable results across different platforms.
To fix this issue, you have two approaches:
- Add an explicit
roleattribute to the element, choosing a role that supports the ARIA attributes you're using. - Use a semantic HTML element that already has an implicit ARIA role. For instance,
<nav>has an implicit role ofnavigation,<button>has an implicit role ofbutton, and<header>has an implicit role ofbanner. This is generally the preferred approach, as it provides built-in keyboard interaction and semantics without extra effort.
When choosing a role, make sure the ARIA states and properties you're using are actually supported by that role. For example, aria-expanded is supported by roles like button, combobox, link, treeitem, and others — but not by every role. Consult the WAI-ARIA roles documentation to verify compatibility.
Examples
Invalid: ARIA property without a role
This <div> uses aria-expanded but has no role, so the validator doesn't know what kind of element this is supposed to be.
<div aria-expanded="true">
Menu contents
</div>
Fixed: Adding an explicit role
Adding role="button" tells assistive technologies that this is a button that can be expanded or collapsed.
<div role="button" aria-expanded="true" tabindex="0">
Menu contents
</div>
Fixed: Using a semantic HTML element instead
A <button> element already has an implicit button role, so no explicit role attribute is needed. This is the preferred approach.
<button aria-expanded="true">
Toggle menu
</button>
Invalid: aria-label on a generic element
A <span> has no implicit role, so aria-label has no meaningful context here.
<span aria-label="Close dialog">X</span>
Fixed: Using a semantic element or adding a role
<button aria-label="Close dialog">X</button>
Or, if you need to use a <span>:
<span role="button" tabindex="0" aria-label="Close dialog">X</span>
Using elements with implicit roles
Many HTML elements already carry implicit ARIA roles, so adding ARIA states and properties to them is valid without an explicit role attribute:
<!-- <nav> has implicit role="navigation" -->
<nav aria-label="Main navigation">
<ul>
<li><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
</ul>
</nav>
<!-- <details> supports aria-expanded implicitly -->
<details aria-describedby="help-text">
<summary>More information</summary>
<p id="help-text">Additional details about this topic.</p>
</details>
As a general rule, always prefer native semantic HTML elements over generic elements with ARIA roles. Native elements come with built-in keyboard support, focus management, and accessibility semantics — reducing the amount of custom code you need to write and maintain.
An element with role="tab" requires a corresponding element with role="tabpanel" in the same document. Without this pairing, assistive technologies cannot associate the tab with the content it controls.
The WAI-ARIA specification defines a tab interface as a set of layered content areas, where only one panel is visible at a time. Each role="tab" element must reference a role="tabpanel" element through the aria-controls attribute, and each role="tabpanel" should reference its tab back using aria-labelledby.
The tabs themselves must be wrapped in a container with role="tablist". The selected tab gets aria-selected="true", while inactive tabs get aria-selected="false". Each tabpanel that is not currently visible should be hidden with the hidden attribute or equivalent CSS.
The W3C validator flags this error when it finds a role="tab" element but no matching role="tabpanel" exists in the document. This can happen when the tab panels are missing entirely, or when they exist but lack the role="tabpanel" attribute.
Invalid example
<div role="tablist">
<button role="tab" aria-selected="true" aria-controls="panel-1">Tab 1</button>
<button role="tab" aria-selected="false" aria-controls="panel-2">Tab 2</button>
</div>
<div id="panel-1">Content for tab 1</div>
<div id="panel-2" hidden>Content for tab 2</div>
The two div elements exist but have no role="tabpanel", so the validator reports the error.
Valid example
<div role="tablist">
<button role="tab" aria-selected="true" aria-controls="panel-1" id="tab-1">Tab 1</button>
<button role="tab" aria-selected="false" aria-controls="panel-2" id="tab-2">Tab 2</button>
</div>
<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">
Content for tab 1
</div>
<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>
Content for tab 2
</div>
Each role="tab" now has a corresponding role="tabpanel". The aria-controls on each tab points to the id of its panel, and aria-labelledby on each panel points back to the id of its tab.
An aria-label attribute on an <a> element is only valid when the link has an accessible role that supports naming — which means the <a> must have an href attribute or an explicit role that accepts a label.
When an <a> element lacks an href attribute, it has the implicit role of generic. The generic role is in the list of roles that do not support naming, so applying aria-label to it is invalid. This is because a generic element has no semantic meaning, and screen readers wouldn't know how to announce the label in a meaningful way.
The most common cause of this error is using <a> as a placeholder or JavaScript-only trigger without an href. An <a> with an href has the implicit role of link, which does support aria-label, so the error won't appear.
You have a few ways to fix this:
- Add an
hrefto make it a proper link (most common fix). - Add an explicit role that supports naming, such as
role="button", if the element acts as a button. - Use a
<button>instead if the element triggers an action rather than navigation. - Remove
aria-labelif it's not needed, and use visible text content instead.
HTML Examples
❌ Invalid: aria-label on an <a> without href
<a aria-label="Close menu" onclick="closeMenu()">✕</a>
The <a> has no href, so its implicit role is generic, which does not support naming.
✅ Fix option 1: Add an href
<a href="/close" aria-label="Close menu">✕</a>
✅ Fix option 2: Use a <button> instead
<button aria-label="Close menu" onclick="closeMenu()">✕</button>
✅ Fix option 3: Add an explicit role that supports naming
<a role="button" tabindex="0" aria-label="Close menu" onclick="closeMenu()">✕</a>
Using a <button> (option 2) is generally the best choice for interactive elements that perform actions rather than navigate to a URL.
A <b> element without an explicit role has the generic role, and generic elements can't have an accessible name, so aria-label is not allowed on it.
ARIA forbids naming elements with the roles listed in the message. Screen readers often skip an aria-label on these elements, and users never hear it. Setting role="generic" or role="presentation" on the <b> doesn't help either, because both roles are in the list.
The usual cause is a <b> used as a clickable icon, such as the "×" that closes a notice. Keyboard users can't tab to a <b>, and screen readers don't announce it as a button. Replace it with <button type="button">, which takes aria-label, receives focus, and runs its click handler when the user presses Enter or Space.
Adding aria-hidden="true" doesn't clear the message. The validator still flags the aria-label, and nobody hears the label of a hidden element anyway. For a purely decorative <b>, keep aria-hidden="true" and delete aria-label. If the <b> is a symbol that means something by itself, like an asterisk that marks a required field, role="img" makes the label valid. For ordinary bold text, remove aria-label and reword the visible text if it isn't clear enough on its own.
Invalid example
<div class="alert" role="status">
<p>Your changes have been saved.</p>
<b class="alert-close" aria-label="Dismiss message" onclick="this.parentElement.hidden = true">×</b>
</div>
Valid example
<div class="alert" role="status">
<p>Your changes have been saved.</p>
<button type="button" class="alert-close" aria-label="Dismiss message" onclick="this.parentElement.hidden = true">×</button>
</div>
A div element without an explicit role resolves to the generic role, which does not support naming — so adding aria-label to a plain div is invalid.
The aria-label attribute provides an accessible name for an element, but not every element is allowed to have one. The ARIA specification defines certain roles as "naming prohibited," meaning assistive technologies will ignore any accessible name applied to them. The generic role is one of these, and since a div without an explicit role attribute defaults to generic, the aria-label is effectively meaningless.
To fix this, you have two main options: assign an appropriate ARIA role to the div so it becomes a nameable landmark or widget, or switch to a semantic HTML element that already carries a valid role. Common roles that support naming include region, group, navigation, alert, and many others.
If the div is truly just a generic wrapper with no semantic meaning, consider whether aria-label is even needed. Perhaps the label belongs on a child element instead, or the content is already self-describing.
HTML Examples
❌ Invalid: aria-label on a plain div
<div aria-label="User profile section">
<p>Welcome, Jane!</p>
</div>
✅ Fix: Add an appropriate role
<div role="region" aria-label="User profile section">
<p>Welcome, Jane!</p>
</div>
✅ Fix: Use a semantic element instead
<section aria-label="User profile section">
<p>Welcome, Jane!</p>
</section>
The aria-label attribute cannot be used on an <i> element with its default implicit role (generic), because generic elements are not allowed to have accessible names.
The <i> element has an implicit ARIA role of generic, which is one of the roles explicitly prohibited from carrying an aria-label. This restriction exists because screen readers and other assistive technologies ignore accessible names on generic containers — so adding aria-label to a plain <i> element would silently fail to convey any meaning to users who rely on assistive technology.
This issue commonly appears when icon fonts (like Font Awesome) use <i> elements as decorative icons. If the icon is purely decorative, you should hide it from assistive technology with aria-hidden="true" and place the accessible label on a parent or sibling element instead. If the icon conveys meaning on its own, you can assign an appropriate role like role="img" so the aria-label is actually announced.
HTML Examples
❌ Invalid: aria-label on a plain <i> element
<button>
<i class="icon-search" aria-label="Search"></i>
</button>
✅ Fix 1: Decorative icon — hide it, label the parent
<button aria-label="Search">
<i class="icon-search" aria-hidden="true"></i>
</button>
✅ Fix 2: Meaningful icon — assign role="img"
<button>
<i class="icon-search" role="img" aria-label="Search"></i>
</button>
The aria-label attribute cannot be used on a custom element like <menu-item> when it has no explicit role attribute, because it defaults to the generic role, which is in the list of roles that prohibit aria-label.
Custom elements without an explicit role are treated as having the generic role (equivalent to a <span> or <div> in terms of semantics). The WAI-ARIA specification prohibits aria-label on several roles, including generic, because naming these elements creates a confusing experience for assistive technology users — a generic container with a label doesn't convey any meaningful purpose.
To fix this, you need to assign a meaningful role to the <menu-item> element that supports accessible naming. Common choices include role="menuitem", role="link", or role="button", depending on what the element actually does. Since this appears to represent a menu item that navigates to a page, role="menuitem" is likely the most appropriate.
HTML Examples
❌ Invalid: aria-label on an element with implicit generic role
<menu-item
submenu-href="/page"
label="some label"
submenu-title="some submenu title"
aria-label="some aria label">
</menu-item>
✅ Valid: adding an explicit role that supports aria-label
<menu-item
role="menuitem"
submenu-href="/page"
label="some label"
submenu-title="some submenu title"
aria-label="some aria label">
</menu-item>
If the aria-label isn't actually needed (for example, if assistive technology already receives the label through other means in your component), another valid fix is to simply remove aria-label entirely.
A <pre> element has the implicit role generic, which can't have an accessible name, so aria-label on a plain <pre> is an error.
The ARIA specification prohibits names on the roles listed in the message. Screen readers ignore a name set on any of them, so the label never reaches the user. A <pre> without a role attribute counts as generic, and the validator rejects its aria-label until the element has a role from outside that list.
The fix depends on what the <pre> holds. ASCII art and text diagrams are pictures made of characters, and a screen reader reads them out one symbol at a time. Add role="img" so the aria-label replaces that string of symbols with a description. Don't do this for code: the img role hides the element's text, and screen reader users would hear the label instead of the code.
For a code block, a visible caption helps sighted readers too. Wrap the <pre> in a <figure>, put the description in a <figcaption>, and remove the aria-label. If the code block scrolls and has tabindex="0" so keyboard users can scroll it, role="region" gives that focus stop a name and makes the aria-label valid.
Invalid example
<pre aria-label="A cup of coffee drawn with text characters">
( (
) )
........
| |]
\ /
`----'
</pre>
<pre aria-label="Calculating the order total"><code>const total = price * quantity;</code></pre>
Valid example
<pre role="img" aria-label="A cup of coffee drawn with text characters">
( (
) )
........
| |]
\ /
`----'
</pre>
<figure>
<figcaption>Calculating the order total</figcaption>
<pre><code>const total = price * quantity;</code></pre>
</figure>
A span element has an implicit ARIA role of generic, and the aria-label attribute is not allowed on elements with that role.
The span element is a generic inline container with no semantic meaning. Its default ARIA role is generic, which is one of several roles that prohibit naming via aria-label or aria-labelledby. This restriction exists because screen readers are not expected to announce names for generic containers — adding aria-label to them creates an inconsistent and confusing experience for assistive technology users.
To fix this, you have two main options:
- Assign an explicit role to the
spanthat supports naming, such asrole="img",role="group",role="status", or any other role that allowsaria-label. - Use a different element that already has a semantic role supporting
aria-label, such as abutton,a,section, ornav.
If the span is purely decorative or used for styling, consider using aria-hidden="true" instead and placing accessible text elsewhere.
HTML Examples
❌ Invalid: aria-label on a plain span
<span aria-label="Close">✕</span>
✅ Fixed: assign an appropriate role
<span role="img" aria-label="Close">✕</span>
✅ Fixed: use a semantic element instead
<button aria-label="Close">✕</button>
✅ Fixed: hide the decorative span and provide text another way
<button>
<span aria-hidden="true">✕</span>
<span class="visually-hidden">Close</span>
</button>
The <time> element does not support the aria-label attribute when it has no explicit role or when it carries certain generic roles.
The <time> element has an implicit ARIA role of time, but this role is not listed among those that allow aria-label. According to the ARIA in HTML specification, aria-label is only permitted on elements with roles that support naming from author — and the default role of <time> (as well as roles like generic, presentation, paragraph, and others listed in the error) does not qualify.
In practice, the <time> element already conveys its meaning through its visible text content and the machine-readable datetime attribute. Screen readers use the visible text to announce the date, so aria-label is typically unnecessary.
To fix this, simply remove the aria-label attribute and ensure the visible text content is descriptive enough. If you need to provide a more accessible reading of the date, you can adjust the visible text itself or wrap the element with a <span> that has an appropriate role.
Also note the original code has a missing space before datetime — the attribute must be separated from class="Tag" by a space.
HTML Examples
❌ Invalid: aria-label on <time>
<time aria-label="Apr 2." class="Tag" datetime="2026-04-02">
Apr 2.
</time>
✅ Fixed: Remove aria-label and use clear visible text
<time class="Tag" datetime="2026-04-02">
April 2, 2026
</time>
If you truly need aria-label, you can assign an explicit role that supports naming, such as role="text", though this is rarely necessary:
<time role="text" aria-label="April 2nd, 2026" class="Tag" datetime="2026-04-02">
Apr 2.
</time>
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