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>

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.

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 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:

1. 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>

2. 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>

3. 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.

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>

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.

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.

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>

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.