HTML Guide for role
There can only be one visible <main> element in a document. If more are needed (for example for switching between them with JavaScript), only one can be visible, the others should be hidden toggling the hidden attribute.
Example of 2 main elements, where only one is visible:
<main>
<h1>Active main element</h1>
<!-- content -->
</main>
<main hidden>
<h1>Hidden main element</h1>
<!-- content -->
</main>
The HTML <figure> element is used to encapsulate media content, such as an image or graphic, along with a descriptive <figcaption>. When a <figcaption> is present within a <figure>, it inherently provides the semantics of the <figure>, making it self-explanatory without needing an additional role attribute.
Explanation
-
<figure> element: Represents self-contained content, potentially with an optional caption specified by a <figcaption> element. This is inherently recognized for its semantics as a figure with a caption.
-
<figcaption> element: Provides a caption or description for the content of the <figure>. This helps in describing the media or content included in the <figure> element.
-
role attribute: This attribute is used to define an explicit accessibility role for an element. However, in cases where the element’s native semantics are explicit and sufficient, such as a <figure> with a <figcaption>, adding a role attribute might override or conflict with the inherent meaning.
Solution
Remove the role attribute from the <figure> element when it contains a <figcaption>.
Example of Incorrect Code:
<figure role="figure">
<img src="cat.jpg" alt="A cute cat">
<figcaption>A cute cat looking at the camera.</figcaption>
</figure>
Corrected Code:
<figure>
<img src="cat.jpg" alt="A cute cat">
<figcaption>A cute cat looking at the camera.</figcaption>
</figure>
In the corrected example, the <figure> element does not have a role attribute, allowing it to maintain its inherent semantic value.
A role="cell" element must be a child of an element with role="row" for correct ARIA relationships.
According to the ARIA specification, role="cell" should be directly contained within a parent with role="row", which itself should usually be inside an element with role="rowgroup" or role="table". This structure allows assistive technologies to interpret your table semantics correctly.
Correct Structure Example:
<div role="table">
<div role="row">
<div role="cell">Row 1, Cell 1</div>
<div role="cell">Row 1, Cell 2</div>
</div>
<div role="row">
<div role="cell">Row 2, Cell 1</div>
<div role="cell">Row 2, Cell 2</div>
</div>
</div>
Incorrect Structure Example (missing row):
<div role="table">
<div role="cell">Cell without row</div>
</div>
How to fix:
Wrap any element with role="cell" inside an element with role="row". This ensures both validity and proper accessibility support.
A role="columnheader" element must be a child of or associated with a role="row" element.
In HTML, ARIA roles such as columnheader are used to improve accessibility for assistive technologies. According to the ARIA specification, a columnheader role should appear inside an element with role="row", which itself should be inside an element with role="table" or role="grid". This structure mimics how native tables are constructed with <th> elements inside <tr>s.
Correct structure:
- role="table" or role="grid" contains one or more elements with role="row".
- Each role="row" contains one or more elements with role="columnheader" (or role="cell").
Example using ARIA roles for a simple table:
<div role="table" aria-label="Sample Table">
<div role="row">
<div role="columnheader">Name</div>
<div role="columnheader">Age</div>
</div>
<div role="row">
<div role="cell">Alice</div>
<div role="cell">30</div>
</div>
</div>
Best practice:
Whenever possible, use native table elements, which have built-in roles and accessibility, reducing the chance of ARIA misuse.
Example using native table markup:
<table>
<tr>
<th>Name</th>
<th>Age</th>
</tr>
<tr>
<td>Alice</td>
<td>30</td>
</tr>
</table>
Ensure that any element with role="columnheader" is always contained within a parent with role="row". Avoid placing role="columnheader" directly inside a container without the appropriate role="row" ancestor.
To fix the W3C HTML Validator issue stating that an element with a role="menuitem" must be contained in, or owned by, an element with role="menubar" or role="menu", you need to ensure that your menuitem elements are properly nested within a menubar or menu element. This is important for accessibility, as it helps assistive technologies understand the structure and relationship of the elements.
The menuitem role indicates the element is an option in a set of choices contained by a menu or menubar.
Here is a step-by-step guide to fixing this issue:
1. Using role="menubar"
If your menuitem elements are part of a horizontal menu (like a navigation bar), they should be nested within an element with role="menubar".
Example:
<nav role="menubar">
<div role="menuitem">Home</div>
<div role="menuitem">About</div>
<div role="menuitem">Contact</div>
</nav>
2. Using role="menu"
If your menuitem elements are part of a submenu or a vertical menu, they should be contained within an element with role="menu".
Example:
<div role="menu">
<div role="menuitem">Item 1</div>
<div role="menuitem">Item 2</div>
<div role="menuitem">Item 3</div>
</div>
Ensuring Proper Nesting
Ensure that all your menuitem elements are either directly or indirectly (via a child-parent relationship) contained within a menubar or menu element.
Complete Example with Nested Menus:
Here is a more complex example, including nested menus for a drop-down scenario.
Example:
<nav role="menubar">
<div role="menuitem">Home</div>
<div role="menuitem">
About
<div role="menu">
<div role="menuitem">Team</div>
<div role="menuitem">History</div>
</div>
</div>
<div role="menuitem">Contact</div>
</nav>
In this example, the main navigation (menubar) contains menuitem elements, and one of those menuitem elements contains a nested menu with additional menuitem elements inside it.
By ensuring your menuitem elements are contained within appropriate parent elements (menubar or menu), you will resolve the W3C HTML Validator issue and improve your web page’s accessibility.
Elements with the role tab must either be a child of an element with the tablist role, or have their id part of the aria-owns property of a tablist.
An element with the tab role controls the visibility of an associated element with the tabpanel role. The common user experience pattern is a group of visual tabs above, or to the side of, a content area, and selecting a different tab changes the content and makes the selected tab more prominent than the other tabs.
Example:
<div class="tabs">
<div role="tablist" aria-label="Sample Tabs">
<button role="tab" aria-selected="true" aria-controls="panel-1" id="tab-1" tabindex="0">
First Tab
</button>
<button role="tab" aria-selected="false" aria-controls="panel-2" id="tab-2" tabindex="-1">
Second Tab
</button>
</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>
A button element, or an element with the role=button attribute, is not allowed to be nested inside an <a> element.
When an img element has an empty alt attribute, its role is implicitly decorative, so it must not specify a role attribute.
The alert role can be used to tell the user an element has been dynamically updated. Screen readers will instantly start reading out the updated content when the role is added. The element <ul> doesn’t accept this kind of role, consider using other element like <p> or <div>.
The alert role is used to communicate an important and usually time-sensitive message to the user. When this role is added to an element, the browser will send out an accessible alert event to assistive technology products which can then notify the user about it. The alert role is most useful for information that requires the user’s immediate attention.
Using role="article" on a <section> element is invalid because article is not a permitted value for the role attribute.
The role attribute in HTML is used to define ARIA roles that describe the purpose of an element for assistive technologies. Only specific, predefined ARIA roles are valid per the WAI-ARIA specification. article is not a recognized ARIA role—use document or other appropriate roles instead, or omit the role attribute entirely. The <article> and <section> elements already have implicit roles, so manual role assignment is rarely necessary or useful for these elements.
Valid uses:
- Use <article> without a role attribute for content that is self-contained and intended to be independently distributable or reusable.
- Use <section> for grouping related content and omit the role attribute unless a specific ARIA landmark role is needed (such as region).
Example: use <article> for standalone content
<article>
<h2>News headline</h2>
<p>News content goes here.</p>
</article>
Example: use <section> without a role attribute for generic grouping
<section>
<h2>Introduction</h2>
<p>Section content.</p>
</section>
An element like <h1>, <h2>, etc., used to define a heading, does not accept the button role.
The following HTML code is invalid because the <h2> element can’t have role="button"
<h2 role="button">Some heading</h2>
Instead, you can nest the <h2> inside a <div> with that role. In this case however, browsers automatically apply role presentation to all descendant elements of any button element as it is a role that does not support semantic children.
<div role="button">
<h2>Some heading</h2>
</div>
A <li> element, used to define a list item, does not accept the button role.
This HTML code is invalid because the <li> elements can’t have role="button":
<ul>
<li role="button">One</li>
<li role="button">Two</li>
</ul>
The role attribute value combobox is not valid on an input element according to the W3C HTML standard.
The role="combobox" is valid only when applied to an element that acts as a container for the combo box widget, usually a div or similar element, and not directly to a native HTML input. Native input elements of type "text" or "search" already have implicit roles and accessibility semantics. To create an accessible combobox, wrap the input inside a container element with role="combobox" and use appropriate ARIA attributes.
Incorrect Implementation:
<input type="text" role="combobox" aria-autocomplete="list">
Correct Implementation:
<div role="combobox" aria-haspopup="listbox" aria-owns="suggestions" aria-expanded="false">
<input type="text" aria-autocomplete="list" aria-controls="suggestions">
</div>
<ul id="suggestions" role="listbox">
<li role="option" id="option1">Option 1</li>
<li role="option" id="option2">Option 2</li>
</ul>
Explanation of attributes:
- role="combobox": Applied to the container (<div>) to define the accessible widget.
- aria-haspopup="listbox": Indicates the presence of a list of suggestions.
- aria-owns / aria-controls: Connects the input and suggestion list.
- aria-expanded: Denotes whether the suggestion list is visible.
- aria-autocomplete: Defines the autocomplete behavior.
This markup ensures better accessibility and passes W3C validation.
The issue arises because “complimentary” is not a valid value for the role attribute on the <aside> element. In HTML, the role attribute is used to provide assistive technologies with extra information about the purpose of the element. The role values are defined by the WAI-ARIA specification.
The correct role for an <aside> element, if explicitly needed, would be complementary (note the spelling with an “e” instead of an “i”). However, the <aside> element has an implicit ARIA role of complementary, and thus it is typically unnecessary to explicitly specify this role unless you are using advanced ARIA techniques.
Correct Example:
<aside>
<h2>Related Information</h2>
<p>Here you can find additional resources and links.</p>
</aside>
If you want to explicitly define the role:
<aside role="complementary">
<h2>Related Information</h2>
<p>Here you can find additional resources and links.</p>
</aside>
Make sure to always use correct ARIA attributes and values to maintain accessibility for users relying on assistive technologies. For a comprehensive list of roles available for usage, refer to the WAI-ARIA specifications.
The value group is not a valid value for the role attribute on an li element according to the W3C HTML specification.
The role attribute defines the semantic purpose of an element for assistive technologies. Common valid ARIA roles for li elements are listitem, not group. The role group is intended for container elements such as ul, ol, or div when grouping related widgets, not for individual list items.
To fix this, remove the role="group" attribute from the li element.
Incorrect:
<ul>
<li role="group">Item 1</li>
<li role="group">Item 2</li>
</ul>
Correct:
<ul>
<li>Item 1</li>
<li>Item 2</li>
</ul>
For most cases with HTML lists, native semantics suffice and no role attribute is needed for li.
The icon value for attribute role is not a valid ARIA role.
ARIA Roles: Overview
ARIA roles are used to enhance accessibility by clearly defining the role and purpose of an element for assistive technologies. However, there are defined roles that you need to adhere to:
- Standard roles include button, checkbox, alert, dialog, img, etc.
- There is no ARIA role named icon.
Solution
To fix the issue, you need to use a valid ARIA role that accurately describes the purpose of the span element. If your intention is to convey that the span contains an icon, you might want to reconsider whether you need a role at all. Often, purely decorative elements should not have a role, or you might use an img role if it conveys a meaningful image.
Here’s how you can address this:
-
No ARIA role (if purely decorative): If the icon is purely decorative and does not add meaningful content to your page, you should remove the role attribute entirely.
<span class="icon"></span>
-
Using img role (if it represents an image): If the span represents an image or an icon that conveys meaningful information, you can use role="img" and provide a proper aria-label.
<span class="icon" role="img" aria-label="Icon Description"></span>
-
Using an appropriate role (if interactive): If the icon is part of an interactive element, you might need a different role. For instance, if the icon is inside a button:
<button> <span class="icon" aria-hidden="true"></span> Button text </button>
Here, aria-hidden="true" is used to hide the decorative icon from screen readers as the text provides the necessary context.
The role attribute value navigation is invalid for a ul element, as it should be used with a nav element or similar suitable elements.
In HTML, the role attribute defines what an element represents in the context of accessible web technologies, primarily for assistive tools like screen readers. The nav element represents a section of a page intended for navigational links, and it inherently provides the role of navigation. If you want to make a ul element serve as navigation, it is more appropriate to use it inside a nav element, or alternatively, set a valid ARIA role on the element itself.
Detailed Explanation
HTML5 introduced a specific set of elements with implicit ARIA roles and behaviors, like the nav element, which implicitly has the navigation role. For backward compatibility or advanced use cases, developers might explicitly set ARIA roles using the role attribute. However, setting an invalid role can lead to accessibility issues, as seen with trying to assign navigation to a ul element.
Instead of applying the navigation role to a ul directly, wrap your ul with a nav element.
The allowed ARIA roles for an ul element are directory, group, listbox, menu, menubar, none, presentation, radiogroup, tablist, toolbar and tree, but not navigation.
Examples
Here is how you can use the nav element with a ul.
<nav>
<ul>
<li><a href="#home">Home</a></li>
<li><a href="#about">About</a></li>
<li><a href="#contact">Contact</a></li>
</ul>
</nav>
There’s no role in ARIA named presentational, you probably mean presentation.
The presentation role and its synonym none remove an element’s implicit ARIA semantics from being exposed to the accessibility tree.
The content of the element will still be available to assistive technologies; it is only the semantics of the container — and in some instance, required associated descendants — which will no longer expose their mappings to the accessibility API.
An element with role="rowgroup" is a group of rows within a tabular structure. A rowgroup contains one or more rows of cells, grid cells, column headers, or row headers within a grid, table or treegrid, as in this example:
<div
role="table"
aria-label="Populations"
aria-describedby="country_population_desc">
<div id="country_population_desc">World Populations by Country</div>
<div role="rowgroup">
<div role="row">
<span role="columnheader" aria-sort="descending">Country</span>
<span role="columnheader" aria-sort="none">Population</span>
</div>
</div>
<div role="rowgroup">
<div role="row">
<span role="cell">Finland</span>
<span role="cell">5.5 million</span>
</div>
<div role="row">
<span role="cell">France</span>
<span role="cell">67 million</span>
</div>
</div>
</div>
<input> elements can’t have a search role. Instead, try with <input type="search">.
<input> elements of type search are text fields designed for the user to enter search queries into. These are functionally identical to text inputs, but may be styled differently depending on the user agent.
The search role is a landmark. Landmarks can be used by assistive technology to quickly identify and navigate to large sections of the document. The search role is added to the container element that encompasses the items and objects that, as a whole, combine to create search functionality. When a <form> is a search form, use the search role on the form.
Example of a search form:
<form role="search">
<label for="search-input">Search this site</label>
<input type="search" id="search-input" name="search">
<input value="Submit" type="submit">
</form>
Using role="section" on a <section> element is unnecessary and not recommended.
The <section> element is a semantic HTML5 element that is used to define sections within a document. A <section> inherently carries the semantics of a structural region, so you don’t need to explicitly declare a role attribute for it. The role attribute in HTML is mainly used to enhance accessibility by explicitly defining the purpose of an element when the element’s native HTML semantics are missing or insufficient. However, in this case, since <section> is already semantically meaningful, assigning a role="section" results in redundancy and can cause validation warnings or errors.
HTML5 and ARIA (Accessible Rich Internet Applications) guidelines suggest only using roles when absolutely necessary. Misusing roles can lead to confusion for assistive technologies, potentially impacting user accessibility.
Here’s a correct use of the <section> element without the role attribute:
<!DOCTYPE html>
<html lang="en">
<head>
<title>Document Title</title>
</head>
<body>
<header>
<h1>Website Header</h1>
</header>
<section>
<h2>Section Heading</h2>
<p>This is a paragraph within the section.</p>
</section>
<footer>
<p>Website Footer</p>
</footer>
</body>
</html>
By removing role="section", you leverage the semantic meaning that the <section> element already provides, ensuring cleaner, more accessible, and standards-compliant HTML.
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.