HTML Guide
Using the ARIA role value listitem
on an article
element is invalid.
The article
element is a landmark with an implicit role of article
, and ARIA requires roles to match the element’s semantics. The listitem
role is only valid for elements that are direct children of a list
-type container with role list
or group
, or native lists like ul
/ol
. If you want an article in a list, wrap each article
in a proper list container and either rely on native semantics (ul
/ol
) or use a neutral container with an explicit role="list"
. Avoid overriding landmark elements with unrelated roles. Use the role
attribute only when necessary, and prefer native HTML semantics.
HTML Examples
Invalid: article with role=”listitem”
<article role="listitem">
<h2>News item</h2>
<p>Details...</p>
</article>
Valid options
<!-- Option A: Use native list semantics -->
<ul>
<li>
<article>
<h2>News item</h2>
<p>Details...</p>
</article>
</li>
<li>
<article>
<h2>Another item</h2>
<p>More details...</p>
</article>
</li>
</ul>
<!-- Option B: ARIA list with neutral containers -->
<div role="list">
<div role="listitem">
<article>
<h2>News item</h2>
<p>Details...</p>
</article>
</div>
<div role="listitem">
<article>
<h2>Another item</h2>
<p>More details...</p>
</article>
</div>
</div>
Learn more:
Related W3C validator issues
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>
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 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>
A <li> element is used to define an item of a list, so adding the listitem role to it is redundant.
The ARIA listitem role can be used to identify an item inside a list of items. It is normally used in conjunction with the list role, which is used to identify a list container.
<section role="list">
<div role="listitem">List item 1</div>
<div role="listitem">List item 2</div>
<div role="listitem">List item 3</div>
</section>
When possible, you should use the appropriate semantic HTML elements to mark up a list and its list items — <ul> or <ol>, and <li>. For example:
<ul>
<li>List item 1</li>
<li>List item 2</li>
<li>List item 3</li>
</ul>
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 this issue, ensure that an element with role="listitem" is contained within an element with role="list" or role="group". Here’s how you can structure your HTML correctly:
Incorrect Example
<div role="listitem">Item 1</div>
<div role="listitem">Item 2</div>
Correct Example
<div role="list">
<div role="listitem">Item 1</div>
<div role="listitem">Item 2</div>
</div>
Alternatively, you can use role="group" if it’s a nested list.
Correct Example with Nested List
<div role="list">
<div role="listitem">Item 1</div>
<div role="group">
<div role="listitem">Item 1.1</div>
<div role="listitem">Item 1.2</div>
</div>
<div role="listitem">Item 2</div>
</div>
This ensures that the role="listitem" elements are correctly contained.
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.