HTML Guide

A button element, or an element with the role=button attribute, is not allowed to be nested inside an <a> element.

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>

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

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>

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