HTML Guide

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

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

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>

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>

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>