HTML Guides for tabindex

When an element has role="button", assistive technologies treat it as a single interactive control — just like a native <button>. Users expect to tab to it once, and then activate it with Enter or Space. If a focusable descendant (an element with tabindex) exists inside that button, it creates a second tab stop within what should be a single control. This breaks the expected interaction model and confuses both keyboard users and screen readers.

The WAI-ARIA specification explicitly states that certain roles, including button, must not contain interactive or focusable descendants. This is because a button is an atomic widget — it represents one action and should receive focus as a single unit. When a screen reader encounters a role="button" element, it announces it as a button and expects the user to interact with it directly. A nested focusable element disrupts this by creating an ambiguous focus target: should the user interact with the outer button or the inner focusable element?

This issue commonly arises when developers wrap inline elements like <span> or <a> with tabindex inside a <div role="button">, often to style parts of the button differently or to add click handlers. The correct approach is to ensure only the outermost button-like element is focusable.

How to fix it

1. Use a native <button> element. This is always the best solution. Native buttons handle focus, keyboard interaction (Enter and Space key activation), and accessibility announcements automatically — no role or tabindex needed.

2. Move tabindex to the role="button" container. If you must use role="button" (for example, when a <div> needs to behave as a button due to design constraints), place tabindex="0" on the container itself and remove tabindex from all descendants.

3. Remove tabindex from descendants. If the inner element doesn’t actually need to be independently focusable, simply remove the tabindex attribute from it.

When using role="button" on a non-interactive element, remember you also need to implement keyboard event handlers for Enter and Space to fully replicate native button behavior.

Examples

Incorrect: focusable descendant inside role="button"

<div role="button">
  <span tabindex="0">Click me</span>
</div>

The <span> with tabindex="0" creates a focusable element inside the role="button" container, which violates the ARIA authoring rules.

Incorrect: anchor element inside role="button"

<div role="button" tabindex="0">
  <a href="/action" tabindex="0">Perform action</a>
</div>

Even though the container itself is focusable, the nested <a> with tabindex is also focusable, creating two tab stops for what should be a single control.

Correct: use a native <button> element

<button>Click me</button>

A native <button> handles focus, keyboard events, and accessibility semantics out of the box with no additional attributes.

Correct: move tabindex to the role="button" container

<div role="button" tabindex="0">
  <span>Click me</span>
</div>

The tabindex="0" is on the role="button" element itself, and the inner <span> is not independently focusable.

Correct: native button with styled inner content

<button>
  <span class="icon">★</span>
  <span class="label">Favorite</span>
</button>

You can still use inner elements for styling purposes inside a <button> — just don’t add tabindex to them. The button manages focus as a single unit, and screen readers announce the combined text content.

The <a> element is an interactive content element — it’s already focusable and keyboard-navigable by default. When you place an element with a tabindex attribute inside a link, you create a nested focus target. This means that keyboard users and screen readers encounter two (or more) focusable items where only one is expected. The browser may not handle this consistently, and the user experience becomes unpredictable: should pressing Enter activate the link, or the inner focusable element?

The HTML specification defines that certain interactive elements must not be nested within other interactive elements. An <a> element’s content model explicitly forbids interactive content as descendants. Adding tabindex to any element makes it interactive (focusable), which violates this rule.

This matters for several reasons:

• Accessibility: Screen readers may announce nested focusable elements in confusing ways, or skip them entirely. Users relying on keyboard navigation may get trapped or confused by unexpected tab stops inside a link.
• Standards compliance: The W3C validator flags this as an error because it violates the HTML content model for anchor elements.
• Browser inconsistency: Different browsers may handle nested focusable elements differently, leading to unpredictable behavior across platforms.

To fix this issue, you have a few options:

1. Remove the tabindex attribute from the descendant element if it doesn’t need to be independently focusable.
2. Restructure your markup so the focusable element is a sibling of the <a> element rather than a descendant.
3. Rethink the design — if you need multiple interactive targets in the same area, consider using separate elements styled to appear as a single unit.

Examples

❌ Invalid: Element with tabindex inside an <a> element

<a href="/products">
  <div tabindex="0">
    <h2>Our Products</h2>
    <p>Browse our full catalog</p>
  </div>
</a>

The <div> has tabindex="0", making it focusable inside an already-focusable <a> element. This creates conflicting focus targets.

✅ Fixed: Remove tabindex from the descendant

<a href="/products">
  <div>
    <h2>Our Products</h2>
    <p>Browse our full catalog</p>
  </div>
</a>

Since the <a> element is already focusable and clickable, the inner <div> doesn’t need its own tabindex. Removing it resolves the conflict.

❌ Invalid: span with tabindex inside a link

<a href="/profile">
  <span tabindex="-1">User Name</span>
</a>

Even tabindex="-1" (which removes the element from the natural tab order but still makes it programmatically focusable) triggers this validation error when used inside an <a> element.

✅ Fixed: Remove tabindex from the span

<a href="/profile">
  <span>User Name</span>
</a>

❌ Invalid: Button-like element nested inside a link

<a href="/dashboard">
  <div tabindex="0" role="button">Settings</div>
</a>

✅ Fixed: Separate the interactive elements

<div class="card-actions">
  <a href="/dashboard">Dashboard</a>
  <button type="button">Settings</button>
</div>

If you truly need two distinct interactive elements, place them as siblings rather than nesting one inside the other. Use CSS to style them as a cohesive visual unit if needed.

The HTML specification defines button as an interactive content element that accepts phrasing content as its children, but explicitly forbids interactive content as descendants. When you add a tabindex attribute to an element, you make it focusable and potentially interactive, which violates this content model restriction.

This rule exists for important reasons. A button element is a single interactive control — when a user presses Tab, the entire button receives focus as one unit. If elements inside the button also have tabindex, screen readers and keyboard users encounter nested focusable items within what should be a single action target. This creates confusing, unpredictable behavior: users may tab into the button’s internals without understanding the context, and assistive technologies may announce the inner elements separately, breaking the expected interaction pattern.

Browsers may also handle nested focusable elements inconsistently. Some may ignore the inner tabindex, while others may allow focus on the nested element but not properly trigger the button’s click handler, leading to broken functionality.

How to fix it

The most straightforward fix is to remove the tabindex attribute from any elements inside the button. If the inner element was given tabindex="0" to make it focusable, it doesn’t need it — the button itself is already focusable. If it was given tabindex="-1" to programmatically manage focus, reconsider whether that focus management is necessary within a button context.

If you genuinely need multiple interactive elements in the same area, restructure your markup so that the interactive elements are siblings rather than nested inside a button.

Examples

❌ Incorrect: span with tabindex inside a button

<button type="button">
  <span tabindex="0">Click me</span>
</button>

The span has tabindex="0", making it a focusable descendant of the button. This violates the content model.

✅ Correct: Remove tabindex from the descendant

<button type="button">
  <span>Click me</span>
</button>

The span no longer has tabindex, so the button behaves as a single focusable control.

❌ Incorrect: Multiple focusable elements inside a button

<button type="button">
  <span tabindex="0" class="icon">★</span>
  <span tabindex="-1" class="label">Favorite</span>
</button>

Both inner span elements have tabindex attributes, which is invalid regardless of the tabindex value.

✅ Correct: Style inner elements without making them focusable

<button type="button">
  <span class="icon">★</span>
  <span class="label">Favorite</span>
</button>

✅ Correct: Restructure if separate interactions are needed

If you need an icon and a separate action side by side, use sibling elements instead of nesting:

<span class="icon" aria-hidden="true">★</span>
<button type="button">Favorite</button>

This keeps the button as a clean, single interactive element while placing the decorative icon outside of it.

The tabindex attribute controls whether and in what order an element can receive keyboard focus. The W3C validator reports this error when it encounters tabindex="" because the HTML specification requires the attribute’s value to be a valid integer — and an empty string cannot be parsed as one. This commonly happens when a value is accidentally omitted, when a template engine outputs a blank value, or when a CMS generates the attribute without a proper default.

Why this matters

Keyboard navigation is fundamental to web accessibility. Screen readers and assistive technologies rely on tabindex values to determine focus behavior. An empty tabindex attribute creates ambiguity: browsers may ignore it or handle it inconsistently, leading to unpredictable focus behavior for keyboard and assistive technology users. Beyond accessibility, it also means your HTML is invalid according to the WHATWG HTML living standard, which strictly defines tabindex as accepting only a valid integer.

How tabindex works

The attribute accepts an integer value with three meaningful ranges:

• Negative value (e.g., tabindex="-1"): The element can be focused programmatically (via JavaScript’s .focus()), but it is excluded from the sequential keyboard tab order.
• tabindex="0": The element is added to the natural tab order based on its position in the document source. This is the most common way to make non-interactive elements (like a <div> or <span>) keyboard-focusable.
• Positive value (e.g., tabindex="1", tabindex="5"): The element is placed in the tab order ahead of elements with tabindex="0" or no tabindex, with lower numbers receiving focus first. Using positive values is generally discouraged because it overrides the natural document order and makes focus management harder to maintain.

How to fix it

1. If the element should be focusable in tab order, set tabindex="0".
2. If the element should only be focusable programmatically, set tabindex="-1".
3. If you don’t need custom focus behavior, remove the tabindex attribute entirely. Interactive elements like <a>, <button>, and <input> are already focusable by default.
4. If a template or CMS generates the attribute, ensure the logic provides a valid integer or omits the attribute when no value is available.

Examples

❌ Empty tabindex value (triggers the error)

<div tabindex="">Click me</div>

<button tabindex="">Submit</button>

✅ Fixed: valid integer provided

<div tabindex="0">Click me</div>

<button tabindex="-1">Submit</button>

✅ Fixed: attribute removed when not needed

Interactive elements like <button> are focusable by default, so tabindex can simply be removed:

<button>Submit</button>

✅ Fixed: conditional rendering in a template

If you’re using a templating system, ensure the attribute is only rendered when a valid value exists:

<!-- Instead of always outputting tabindex -->

<!-- Bad: <div tabindex="{{ tabindexValue }}"> -->


<!-- Only output the attribute when a value is set -->

<div tabindex="0">Interactive content</div>

A note on positive tabindex values

While positive integers like tabindex="1" or tabindex="3" are technically valid, they force a custom tab order that diverges from the visual and DOM order of the page. This creates confusion for keyboard users and is difficult to maintain as pages evolve. The WAI-ARIA Authoring Practices recommend avoiding positive tabindex values. Stick with 0 and -1 in nearly all cases.