All rules

Sheath rule

a11y-no-positive-tabindex

Disallow positive tabindex values as they disrupt the natural tab order.
Package
Core
Category
Accessibility
Default severity
warning by default
Auto-fix
Auto-fix available

(dangerous)

#Why

A positive tabindex does not nudge an element forward. It moves the element into a separate sequence that runs before every element with tabindex="0" or none at all. One tabindex="1" therefore reorders the whole page, and keeping that sequence correct means renumbering it every time the markup changes.

Only tabindex="0" (add to tab order) and tabindex="-1" (programmatic focus only) should be used.

The fixer changes a positive value to tabindex="0". This is dangerous and requires --dangerous, because it changes keyboard navigation order.

#Examples

#Bad

<!-- Positive tabindex values -->

<input type="text" tabindex="1">

<input type="text" tabindex="2">

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



<!-- Any positive value is problematic -->

<a href="/link" tabindex="99">Link</a>



<!-- A leading plus sign is valid integer syntax and is still positive -->

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



<!-- HTML consumes the leading integer even when characters follow it -->

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

#Good

<!-- Natural tab order (no tabindex needed) -->

<input type="text">

<input type="text">

<button>Submit</button>



<!-- tabindex="0" to add non-focusable elements to tab order -->

<div role="button" tabindex="0">Custom Button</div>



<!-- tabindex="-1" for programmatic focus only -->

<div id="modal" tabindex="-1">Modal content</div>



<!-- Negative tabindex removes from tab order -->

<button tabindex="-1">Skip this button</button>

#Valid tabindex Values

Use 0 or -1 according to whether the element belongs in the normal keyboard tab order.

Value Behavior
Not specified Default behavior (focusable elements are in tab order)
0 Add to tab order in DOM position
-1 Remove from tab order, but focusable via JavaScript
1+ Avoid - Creates explicit order before tabindex="0" elements

#Notes

  • Restructure your HTML to achieve the desired tab order
  • Use CSS for visual positioning while keeping logical DOM order
  • tabindex="-1" is useful for focus management in modals and error handling
  • HTML integer parsing skips leading ASCII whitespace and consumes a numeric prefix. Values such as 1.5 and 1e2 therefore behave as 1, not as invalid values
  • Screen reader users often navigate by other means (headings, landmarks), not just tab

#References

#Related Rules