Navigation using the Tab key should be restricted to elements on the page that users can interact with.

Why is this an issue?

The misuse of the tabIndex property can lead to several issues:

How to fix it

If the element is not meant to be interactive, remove the tabIndex property or set it to -1 so it is skipped by sequential keyboard navigation.

If the element is meant to be interactive, prefer a native interactive element such as <button> or <a href>. When a custom widget is required, give it the appropriate interactive role, keep it keyboard reachable, and implement the keyboard behavior that role expects.

Code examples

Noncompliant code example

<div tabIndex={0}>Save</div>

Compliant solution

<button type="button">Save</button>

Compliant solution

<div
  role="button"
  tabIndex={0}
  onClick={save}
  onKeyDown={event => {
    if (event.key === 'Enter' || event.key === ' ') {
      save();
    }
  }}
>
  Save
</div>

Exceptions

This rule accepts tabIndex={0} on elements with role="tabpanel". This matches the WAI-ARIA Tabs pattern, which allows the tabpanel itself to receive focus when its first meaningful content is not focusable.

<div role="tabpanel" tabIndex={0}>
  {content}
</div>

Editable HTML elements accept user input and can receive focus. This rule accepts tabIndex={0} on native HTML tags whose names are not shared with SVG. The element must have one direct, statically enabled attribute spelled exactly contentEditable in JSX. A nested editing host can need tabIndex={0} to join sequential keyboard navigation.

Enabled values include contentEditable, contentEditable="true", and contentEditable="plaintext-only". A template literal without substitutions can also set one of these values.

<div contentEditable tabIndex={0} />

This exception requires a single direct contentEditable attribute with a statically enabled value and no attribute spreads. Disabled values such as contentEditable="false" and dynamic values such as contentEditable={isEditable} do not qualify. Invalid values, duplicate contentEditable attributes (including case variants), JSX components, differently cased attribute names, and tag names shared with SVG, such as a and title, also do not qualify. Some of these cases can still produce editable HTML elements, so a remaining report may be a false positive.

The rule checks tag names and surrounding JSX to determine whether an element is in the HTML namespace. HTML elements inside SVG foreignObject can be editing hosts and qualify for this exception. The rule cannot always determine the namespace across component boundaries. If a component renders an HTML-only tag, such as div, in the SVG or MathML namespace, the rule may apply this exception even though the element is not an HTML editing host, causing an issue to be missed.

Resources

Documentation