HTML Guide for role
The role="tabpanel" attribute is not permitted on the article element according to W3C and WHATWG HTML specifications.
The role attribute helps describe the purpose of an element for assistive technologies. The value tabpanel indicates a section of a tab interface and should be used only with elements suited to that role—typically generic containers like div or section, not article. The article element has its own landmark meaning and should not be used for widgets such as tab panels.
Correct usage:
- Use role="tabpanel" on a div or section element.
- Use role="tablist" on the container of the tabs.
- Use role="tab" on each tab.
Incorrect:
<article role="tabpanel" id="panel1">
Tab panel content here.
</article>Correct:
<div role="tabpanel" id="panel1">
Tab panel content here.
</div>Full example:
<!DOCTYPE html>
<html lang="en">
<head>
<title>Tabpanel Example</title>
</head>
<body>
<div role="tablist">
<button role="tab" aria-controls="panel1" aria-selected="true">Tab 1</button>
<button role="tab" aria-controls="panel2" aria-selected="false">Tab 2</button>
</div>
<div role="tabpanel" id="panel1">
Tab panel content here.
</div>
<div role="tabpanel" id="panel2" hidden>
Tab panel 2 content here.
</div>
</body>
</html>Replace the article element with a div or section when assigning the tabpanel role to ensure your markup is valid and accessible.
The role attribute in HTML is used to define the accessibility role of an element, which helps assistive technologies understand the purpose or type of the element. The value tabpanel is not appropriate for a <ul> element, which is used for unordered lists.
The role of tabpanel is intended to be used with elements that represent a tab panel, which is part of a tabbed interface. A tabbed interface consists of elements with roles like tablist, tab, and tabpanel. Typically, tabpanel is used with containers that house the content associated with a tab, such as a <div>.
To fix this error, ensure that the tabpanel role is applied to the correct element. Here’s a simple example of how a tab interface can be structured correctly:
<div role="tablist" aria-label="Sample Tabs">
<button role="tab" aria-controls="panel-1" id="tab-1">Tab 1</button>
<button role="tab" aria-controls="panel-2" id="tab-2">Tab 2</button>
</div>
<div role="tabpanel" id="panel-1" aria-labelledby="tab-1" hidden>
<p>Content for Tab 1.</p>
</div>
<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>
<p>Content for Tab 2.</p>
</div>In this example:
- The role tablist is applied to the container element that directly contains the tab elements.
- Each button serving as a tab has the role of tab.
- Each tab panel, which contains the content for a tab, has the role of tabpanel.
Avoid using tabpanel on non-semantic or incorrectly associated elements like <ul>. Instead, use elements like <div> or <section> for tab panels, ensuring the roles align with the intended roles in a tabbed interface.
A <a> tag element is missing required attributes, depending on other present attributes.
Depending on the use of other HTML attributes, an <a> tag may require additional attributes. For example, when using aria-selected to build a tab list, this is an example of valid code using role, aria-selected, aria-controls and aria-labelledby:
<div class="tab-interface">
<div role="tablist" aria-label="Sample Tabs">
<span
role="tab"
aria-selected="true"
aria-controls="panel-1"
id="tab-1"
tabindex="0">
First Tab
</span>
<span
role="tab"
aria-selected="false"
aria-controls="panel-2"
id="tab-2"
tabindex="-1">
Second Tab
</span>
</div>
<div id="panel-1" role="tabpanel" tabindex="0" aria-labelledby="tab-1">
<p>Content for the first panel</p>
</div>
<div id="panel-2" role="tabpanel" tabindex="0" aria-labelledby="tab-2" hidden>
<p>Content for the second panel</p>
</div>
</div>
The <a> element requires either a href attribute, or a role attribute.
In HTML, the <button> element is used to create interactive buttons. The W3C HTML Validator message suggests that your <button> element might be missing certain attributes that are typically expected for accessibility or functionality.
Understanding the Required Attributes
-
type Attribute:
-
The type attribute specifies the behavior of the button. It can take one of the following values:
- submit: Submits the form data to the server.
- reset: Resets the form data to its initial values.
- button: A generic button with no default behavior.
- If omitted, the default value is submit when the button is within a form.
<button type="button">Click me</button> -
The type attribute specifies the behavior of the button. It can take one of the following values:
-
role and aria-checked Attributes:
- These attributes are related to ARIA (Accessible Rich Internet Applications) roles and states, which enhance accessibility by providing semantic meaning to assistive technologies.
- The role attribute defines the type of widget the button is supposed to represent, for example, role="switch" or role="checkbox".
- If using role="checkbox" or role="switch", the aria-checked attribute indicates whether the button is checked (true), unchecked (false), or if its state is indeterminate (mixed).
<!-- Example for a button acting as a checkbox --> <button type="button" role="checkbox" aria-checked="false">Toggle Option</button>
Recommendations
- Always define the type attribute to clearly specify the button’s intended behavior, especially within forms.
- If the button acts like a toggle control such as a checkbox or switch, include the appropriate role and use aria-checked to reflect its current state.
- Ensure alignment of ARIA attributes with the intended behavior and visual representation of the button for users, both with and without assistive technologies.
Using aria-required on a div element requires more context about that element, by providing one of the attributes aria-expanded, aria-valuemax, aria-valuemin, aria-valuenow, role.
When possible, you should prefer semantic tags like input, select and textarea, and use the required attribute, but when form controls are created using non-semantic elements, such as a div element, the aria-required attribute should be included with a value of true to indicate to assistive technologies that user input is required on the element for the form to be submittable. In that case, other attributes might be needed to make the element valid.
For example, we could build a radiogroup using a div like this:
<div aria-required="true">
<div data-value="One"></div> 1
<div data-value="Two"></div> 2
<div data-value="Three"></div> 3
</div>This HTML snippet would then be decorated using CSS and added functionality using JavaScript. However, the W3C validator will complain that the element div is missing one of the attributes aria-expanded, aria-valuemax, aria-valuemin, aria-valuenow, role.
We can fix that by adding the appropiate role to that div element, like this:
<div aria-required="true" role="radiogroup">
<div data-value="One"></div> 1
<div data-value="Two"></div> 2
<div data-value="Three"></div> 3
</div>Here is an example showing how to add the “role” attribute to the “div” element:
<div role="region">
<!-- Your content goes here -->
</div>In this example, the role attribute is added with the value radiogroup. You can choose the appropriate ARIA role based on the purpose or role of your div element.
Remember to also provide the necessary values for the specified attributes if you are adding aria-valuemax, aria-valuemin, or aria-valuenow to ensure proper accessibility and usability of your content.
A span element that conveys special meaning or interactive state must have appropriate ARIA attributes or role to be accessible and pass validation.
The span element is a generic inline container with no semantic meaning. To make it meaningful for assistive technologies (such as screen readers), ARIA attributes or a role attribute should be used when the element represents states, properties, or interactive features.
For example, in the following code the span is used to visually indicate a required field with an asterisk *, but it lacks additional semantic information:
<span class="required" aria-required="true"> *</span>To address this, add role="presentation" (to mark it as purely visual), or use aria-hidden="true" (to hide it from assistive technology), as the asterisk does not have semantic value for screen readers. Only use ARIA required (aria-required="true") on the form control (e.g., input), not on the decorative indicator.
Recommended HTML (decorative asterisk not announced):
<span class="required" aria-hidden="true">*</span>Alternative (if you want to announce “required”): Announce “required” with visually hidden text and use the actual aria-required="true" on the input.
<label for="name">
Name
<span class="required" aria-hidden="true">*</span>
<span class="visually-hidden">Required</span>
</label>
<input id="name" name="name" aria-required="true">This approach ensures accessibility, semantic correctness, and W3C HTML validation compliance.
The W3C HTML Validator issue indicates that your <td> element is missing one or more accessibility attributes: either aria-checked or role. These attributes are normally necessary when the cell content needs to convey a specific role or state, such as a checkbox.
If your td element should not act as a checkbox, you should reconsider the design. Ensure that only semantic roles and attributes appropriate for the content and functionality are used. If the misuse is identified due to incorrect implementation, revisiting and clearing the incorrect attributes might be required.
An element is using ARIA attributes, but its role has not been defined. ARIA defines semantics that can be applied to elements, with these divided into roles (defining a type of user interface element) and states and properties that are supported by a role. Authors must assign an ARIA role and the appropriate states and properties to an element during its life-cycle, unless the element already has appropriate ARIA semantics (via use of an appropriate HTML element). Examples:
<!-- This div uses ARIA but its role is not clear, so it's invalid. -->
<div aria-expanded="true">...</div>
<!-- This div defines clearly its role, so it's valid. -->
<div role="navigation" aria-expanded="true">...</div>
<!-- Nav elements have an implicit navigation role so we don't need the role attribute. -->
<nav aria-expanded="true">...</nav>The article role indicates a section of a page that could easily stand on its own on a page, in a document, or on a website, is implicit when using the <article> tag.
This role indicates a section of a page that could easily stand on its own on a page, in a document, or on a website. It is usually set on related content items such as comments, forum posts, newspaper articles or other items grouped together on one page. It can be added to generic elements like <div> to convey this role, for example:
<div role="article">
<h2>Heading</h2>
<p>Content...</p>
</div>Instead of using this role, it’s preferrable to use the native <article> element like this:
<article>
<h2>Heading</h2>
<p>Content...</p>
</article>The <header> HTML element represents introductory content, typically a group of introductory or navigational aids, and has an implicit role of banner, so specifying this role is redundant.
The following example represents a banner using the role attribute:
<div role="banner">
<img src="companylogo.svg" alt="my company name" />
<h1>Title</h1>
<p>Subtitle</p>
</div>By default, the HTML5 <header> element has an identical meaning to the banner landmark, unless it is a descendant of <aside>, <article>, <main>, <nav>, or <section>, at which point <header> is the heading for that section and not the equivalent of the site-wide banner.
This example uses the <header> element instead of the banner role:
<header>
<img src="companylogo.svg" alt="my company name" />
<h1>Title</h1>
<p>Subtitle</p>
</header>The button role is used to make an element appear as a button control to a screen reader and can be applied to otherwise non-interactive elements like <div>. If you’re already using a <button> element, then it’s redundant to apply it the role button, as that’s implicit.
<!-- Instead of this -->
<button role="button">Buy</button>
<!-- Do this -->
<button>Buy</button>The button role is used to make an element appear as a button control to a screen reader and can be applied to otherwise non-interactive elements like <div>. If you’re already using an <input> element whose type is submit, then it’s redundant to apply it the role button, as that’s implicit.
<!-- Instead of this -->
<input type="submit" role="button">Buy</button>
<!-- Do this -->
<input type="submit">Buy</button>The <summary> HTML element specifies a clickable summary, caption, or legend for a <details> element’s disclosure box. As the <summary> element has an implicit button role, it’s not needed to include it explicitly.
Here’s an example, clicking the <summary> element toggles the state of the parent <details> element open and closed.
<details>
<summary>I have keys but no doors. I have space but no room. You can enter but can’t leave. What am I?</summary>
A keyboard.
</details>Using the <aside> element will automatically communicate a section has a role of complementary, so specifying the role="complementary" is redundant.
The <footer> element represents a footer for its nearest sectioning content, and has an implicit role of contentinfo, so specifying this role is redundant.
The following example marks a <div> as a footer specifying its role:
<div role="contentinfo">
<h2>Footer</h2>
<!-- footer content -->
</div>Using the <footer> element instead is recommended:
<footer>
<h2>Footer</h2>
<!-- footer content -->
</footer>The role="dialog" attribute is redundant when used on a <dialog> element because <dialog> has an implicit dialog role by default.
According to the WHATWG HTML living standard and ARIA in HTML, the <dialog> element already has the appropriate semantics for assistive technologies, so explicitly adding role="dialog" is unnecessary and causes warnings in validators.
Incorrect usage:
<dialog role="dialog">
This is a dialog box.
</dialog>Correct usage:
<dialog>
This is a dialog box.
</dialog>Simply remove the role attribute from the <dialog> element to resolve the warning.
When you encounter the issue where the <a> element is nested inside an element with role="button", it’s important to understand that this can lead to accessibility conflicts. The role="button" indicates that the element is interactive, similar to a button. Nesting an <a> (which is also an interactive element) inside it can confuse assistive technologies.
How to Fix This Issue
You should either change the structure so that the <a> is not inside the button or change the role of the button to avoid this violation. Here are two common approaches to resolve the issue:
Option 1: Remove the <a> Tag
Replace the <a> tag with an appropriate action directly inside the element with role="button".
Example Before:
<div role="button">
<a href="#link">Click here</a>
</div>Example After:
<div role="button" tabindex="0" onclick="location.href='#link';">
Click here
</div>Here, we use JavaScript to navigate to the link when the div is clicked.
Option 2: Remove the role="button"
If the <a> tag is sufficient by itself, you can remove the role="button" from the surrounding element.
Example Before:
<div role="button">
<a href="#link">Click here</a>
</div>Example After:
<a href="#link">Click here</a>This maintains the desired navigation without creating a conflict between the button and link semantics.
A button element is not allowed to contain other button elements, or other elements with role=button.
The button role identifies an element as a button to assistive technology such as screen readers. A button is a widget used to perform actions such as submitting a form, opening a dialog, canceling an action, or performing a command such as inserting a new record or displaying information. Adding role="button" tells assistive technology that the element is a button but provides no button functionality
A <form> element has already a form role, so specifying role="form" in it is redundant.
Instead of:
<form role="form">You can simply write:
<form>This W3C HTML Validator issue indicates that you have assigned a role="group" attribute to a <fieldset> element. In HTML, the <fieldset> element already has an implicit role of group so it’s redundant and unnecessary to explicitly specify it.
To resolve this issue, you simply need to remove the role="group" attribute from the <fieldset> element.
Example of the Issue
Here is an example of problematic HTML:
<form>
<fieldset role="group">
<legend>Personal Information</legend>
<label for="name">Name:</label>
<input type="text" id="name" name="name">
<br>
<label for="age">Age:</label>
<input type="number" id="age" name="age">
</fieldset>
</form>Fixed HTML
To fix this issue, remove the role="group" attribute from the <fieldset> element:
<form>
<fieldset>
<legend>Personal Information</legend>
<label for="name">Name:</label>
<input type="text" id="name" name="name">
<br>
<label for="age">Age:</label>
<input type="number" id="age" name="age">
</fieldset>
</form>The heading role defines this element as a heading to a page or section, and is implicit in tags <h1> to <h6>.
The heading role indicates to assistive technologies that this element should be treated like a heading. Screen readers would read the text and indicate that it is formatted like a heading.
This ARIA role is only needed to add that role to a generic element like <div>, for example:
<div role="heading" aria-level="1">This is a main page heading</div>This defines the text in the <div> to be the main heading of the page, indicated by being level 1 via the aria-level attribute. Opt for using the <h1> (thru <h6>) element instead:
<h1>This is a main page heading</h1>A single <img> element is used to embed an image, so adding the img role to it is redundant.
The ARIA img role can be used to identify multiple elements inside page content that should be considered as a single image. These elements could be images, code snippets, text, emojis, or other content that can be combined to deliver information in a visual manner, for example:
<div role="img" aria-label="Description of the overall image">
<img src="graphic1.png" alt="">
<img src="graphic2.png">
</div>An a element with an href attribute provides a link to a resource, so adding the link role to it is redundant.
When not using semantic HTML for its intended purpose, interactive features must be re-implemented. For example, when role="link" is added to an element, the tab key should enable giving focus to the link and the enter key should execute the link when focused.
Remove the role="list" attribute from the ul element.
The ul (unordered list) element is inherently recognized as a list in HTML. As such, it is automatically associated with the semantic role of a list. Adding role="list" to a ul is redundant and can also confuse browsers and screen readers, potentially leading to inconsistent behavior or impaired accessibility. This attribute is unnecessary because the list role is implicitly defined for this element through HTML specifications, and W3C HTML validation flags it to ensure semantic clarity and best practices.
Example of Incorrect role Usage:
<ul role="list">
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
</ul>Corrected Example Without Unnecessary role:
<ul>
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
</ul>By excluding the role="list", the code adheres to semantic clarity and best practices, complying with W3C standards while maintaining accessibility.