HTML Guide

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

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.

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

An <a> element cannot contain a descendant element with the attribute tabindex.

A button element cannot contain a descendant element with the attribute tabindex.

The aria-expanded attribute can only be true, false, or undefined.

This attribute indicates whether a grouping element is expanded or collapsed.

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>

Spaces are not permitted in the href value for phone links; the phone number must be a continuous string without spaces or slashes.

The href attribute of an anchor (<a>) element defines the link’s destination. For phone numbers, the proper URI scheme is tel:, not callto:. According to the HTML standard and the WHATWG Living Standard, the phone number should contain only digits and may use plus (+) or hyphen (-) characters for formatting, but it should not include spaces or slashes.

Incorrect HTML:

<a href="callto:07142/ 12 34 5">Call us</a>

Correct HTML:

<a href="tel:0714212345">Call us</a>

With country code and optional formatting:

<a href="tel:+49714212345">Call us</a>

For best compatibility and validation, always use the tel: scheme and ensure the phone number string contains only allowed characters.

The href attribute of an <a> element contains an invalid character, that should be properly encoded as a URI percent-encoded character.