Step by Step

The “tabIndex should only be declared on interactive elements” error: what to use instead

8 min read
Mikhail ShaymardanovWeb Quality and Accessibility Expert

The message “tabIndex should only be declared on interactive elements” protects keyboard users from a Tab stop on an element that does nothing. The no-noninteractive-tabindex rule of eslint-plugin-jsx-a11y shows it on a div, a span or an li whose tabIndex is 0 or more. Depending on what the element does, it becomes a <button> or a link, switches to tabIndex={-1}, or loses the attribute.

Sorting every flagged tabIndex


#What does “tabIndex should only be declared on interactive elements” mean?

The rule flags a tabIndex of 0 or more on an element that isn't interactive: that value adds a Tab stop that leads to no action. That key moves the focus from one control to the next, so every useless stop costs one more keypress for anyone working without a mouse. In the plugin's recommended and strict presets, the rule is an error, so it fails the automated build unless the project has downgraded it to a warning.

Three rules keep Tab stops useful, and each flagged element can be checked against them:

  • every Tab stop leads to an action;
  • a button activates with Enter and Space, a link with Enter;
  • an element that only a script focuses stays out of the Tab order.

On the Appointments page of Tallgrass Veterinary Clinic, our React demo, ESLint reports six errors for four elements. The Reschedule control, repeated on three cards by a map, accounts for three of them on a single line, because this div also has a click handler:

src/pages/Appointments.jsx
  42:15  error  Visible, non-interactive elements with click handlers must have at least one keyboard listener  jsx-a11y/click-events-have-key-events
  42:15  error  Avoid non-native interactive elements. If using native HTML is not possible, add an appropriate role and support for tabbing, mouse, keyboard, and touch inputs to an interactive content element  jsx-a11y/no-static-element-interactions
  42:43  error  `tabIndex` should only be declared on interactive elements  jsx-a11y/no-noninteractive-tabindex
  46:29  error  `tabIndex` should only be declared on interactive elements  jsx-a11y/no-noninteractive-tabindex
  53:51  error  `tabIndex` should only be declared on interactive elements  jsx-a11y/no-noninteractive-tabindex
  82:34  error  `tabIndex` should only be declared on interactive elements  jsx-a11y/no-noninteractive-tabindex
 
✖ 6 problems (6 errors, 0 warnings)

The other three errors point to the help text, the error summary and the vaccine history, all set to tabIndex={0}.

#How do you see these Tab stops in Firefox?

Firefox's accessibility inspector can show the tab order: a number on every element that Tab reaches. Open the developer tools, go to the Accessibility tab, then check “Show Tabbing Order”.

On the demo, we counted fourteen stops. The help text and the error summary get numbers 8 and 9, just as the “Book appointment” button gets 13. On those two, though, no key triggers anything. Firefox numbers the page as it is when the box gets checked, and the error summary only shows up after a failed submit. Submit the empty form first, then check the box, or reopen the inspector if the box was already checked.

Screenshot: Firefox on the clinic's Appointments page, with the accessibility inspector open and Show Tabbing Order checked; a number appears above the three Reschedule controls (5, 6 and 7), the help text (8), the error summary (9) and the vaccine history (14).Marker 1. The help text, numbered 8. Marker 2. The error summary, numbered 9. Marker 3. The first Reschedule control, numbered 5.
Out of fourteen stops, Firefox numbers the help textmarker 1, the error summarymarker 2 and the three Reschedule controls, starting with the firstmarker 3: on these five elements, neither Enter nor Space triggers an action.
WAVE accessibility tool: how to read the report, and what to test after zero errors

#What should replace a div with tabIndex 0?

It depends on what the element does: a button or a link if it responds to a click, tabIndex={-1} if a script focuses it, no tabIndex otherwise.

#How do you fix a clickable div with tabIndex 0?

An action calls for a <button type="button">. Going to another page calls for an <a href>. Both join the Tab order with no attribute.

On the clinic demo, the Reschedule div does take focus. When we pressed Enter, though, nothing happened, and Space scrolled the page: on a div, onClick only responds to the mouse, as MDN points out. Turned into a <button> and styled as before, Reschedule now moves focus to the time field with either key, and the three ESLint errors on its line go away.

Screenshot: Pistachio's appointment card, Tuesday, December 1 at 9:30 AM, with the cat's photo and the blue Reschedule control.Marker 1. The Reschedule control on the card.
The Reschedule controlmarker 1 keeps its look; as a button, it responds to Enter and Space, and the three jsx-a11y errors go away.

Avoid

<div className="reschedule" tabIndex={0} onClick={() => reschedule(appt)}>
  Reschedule
</div>

Correct

<button type="button" className="reschedule" onClick={() => reschedule(appt)}>
  Reschedule
</button>

Adding role="button" silences the rule and gives the keyboard nothing: Enter and Space then have to be coded by hand. MDN allows that, while recommending the <button>. WCAG success criterion 2.1.1, Keyboard, asks for everything to work from a keyboard. A clickable element that no key activates fails it, unless another control on the page does the same thing from the keyboard. The European accessibility standard EN 301 549 requires every web page to meet this criterion. It was written as one voluntary way to comply with Directive (EU) 2019/882, the European Accessibility Act.

#When should you use tabIndex -1?

tabIndex={-1} takes an element out of the Tab order while still letting a script move focus to it. The rule never flags it. It's meant for an error message focused after a failed submit, a dialog that opens, or the heading that a React app focuses after a page change, a topic with its own article.

On the demo, the error summary set to tabIndex={0} did get focus when the empty form was submitted, then stayed behind as one more stop before the first field. At -1, the same focus() call still moves focus to it, and Firefox no longer gives it a number.

Screenshot: the Book an appointment form, whose pink error summary lists 2 fields to complete, Reason for visit and Preferred time.Marker 1. The error summary, at the top of the form.
The error summarymarker 1 gets focus when the empty form is submitted; with tabIndex at -1, it drops out of the Tab order.

Avoid

useEffect(() => {
  if (errors.length > 0) summary.current.focus();
}, [errors]);
// …
{errors.length > 0 && (
  <div className="errors" ref={summary} tabIndex={0}>
    <p>{errors.length} fields to complete:</p>
  </div>
)}

Correct

useEffect(() => {
  if (errors.length > 0) summary.current.focus();
}, [errors]);
// …
{errors.length > 0 && (
  <div className="errors" ref={summary} tabIndex={-1}>
    <p>{errors.length} fields to complete:</p>
  </div>
)}

#Should text get a tabIndex “for accessibility”?

No: on text, a list item (li), a section or an article, the attribute comes off. Screen readers already move through this content with their own commands, and text doesn't need focus to be understood, however important it is. The demo's help text therefore loses its tabIndex={0}. It looks the same, and Firefox stops numbering it.

Screenshot: Hazel's appointment card, followed by the line You can reschedule up to 24 hours before your appointment.Marker 1. The help text, under the card.
The help textmarker 1 stays on screen and screen readers still read it, with no Tab stop.

Avoid

<p className="help" tabIndex={0}>
  You can reschedule up to 24 hours before your appointment.
</p>

Correct

<p className="help">
  You can reschedule up to 24 hours before your appointment.
</p>
React Router route changes: update the page title and move focus to the new heading

#Does a scrollable region need tabIndex 0, as axe says?

Only for Safari: Chrome, since version 132, and Firefox already let Tab reach a region that overflows, as long as nothing inside it can take focus. For Safari, the region keeps its tabIndex={0} and gets a role, a name and a comment exempting its line from the rule.

On the clinic demo, the vaccine history is a table that scrolls sideways, with no link or button inside. Axe, Deque's automated testing engine, wants that region to keep its tabIndex={0}, even in Chrome. Its “Scrollable region must have keyboard access” rule only passes if the region carries that tabIndex or contains a focusable element. Without either, Safari won't let the keyboard scroll the table.

#Which browsers reach a scrollable region without tabIndex?

Since version 132, Chrome lets a scrollable region take focus when nothing inside it can. If it contains a button, Tab goes straight to the button. Firefox also lets Tab reach a region that really overflows. Safari doesn't: the bug filed against WebKit, its engine, in July 2024 is still not fixed.

We removed the attribute from the vaccine history. Chrome and Firefox put focus on it with Tab, and the arrow keys then scroll the table. WebKit never reaches it.

Without tabindex, only Safari leaves a scrollable region out of the keyboard path
BrowserScrollable region with no tabindex and nothing focusable inside
Chrome, since version 132Reached with Tab
FirefoxReached with Tab
SafariNever reached

Axe therefore asks for this tabIndex={0} because of Safari alone. The rule's description even ends with “in Safari”. Its maintainers added those words because users kept reporting the alert as a false positive. They're considering retiring the rule if Safari fixes the bug.

#How do you keep this tabIndex without turning the rule off?

As long as the site supports Safari, the tabIndex={0} stays. MDN asks for a role and a name on any container that takes focus, so the region gets role="group" and an accessible name, through aria-labelledby pointing to its “Vaccines” heading. group fits better than region, which is for important sections, the ones people should be able to find among the page's landmarks. Since jsx-a11y doesn't count group among the interactive roles, the rule still flags the region, which therefore needs an exception: an eslint-disable-next-line comment, in curly braces, right above it.

Screenshot: the Vaccines section, with a table wider than its region, cut off on the right in the middle of the Veterinarian column.Marker 1. The region that scrolls around the vaccine table.
The history regionmarker 1 keeps its tabIndex at 0 for Safari and gains a role and a name, and the exception only covers its line.

Avoid

<h2 id="vaccines-title">Vaccines</h2>
<div className="history" tabIndex={0}>
  <table>…</table>
</div>

Correct

<h2 id="vaccines-title">Vaccines</h2>
{/* eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex */}
<div className="history" role="group" aria-labelledby="vaccines-title" tabIndex={0}>
  <table>…</table>
</div>

One detail trips up anyone who copies the example from the rule's documentation: its comment leaves out the jsx-a11y/ prefix. ESLint then responds with Definition for rule 'no-noninteractive-tabindex' was not found and keeps flagging the line.

The other route, the rule's roles option, exempts every role="group" in the project. In that case, write ["tabpanel", "group"]: this list replaces the one from recommended, and without tabpanel, tab panels would get flagged again. Every div with role="group" and tabIndex={0} would then pass without a word, whether it scrolls or not. That's why we recommend the comment, limited to the region that needs it.

// eslint.config.mjs
import jsxA11y from "eslint-plugin-jsx-a11y";
 
export default [
  {
    files: ["**/*.jsx"],
    ...jsxA11y.flatConfigs.recommended,
    rules: {
      ...jsxA11y.flatConfigs.recommended.rules,
      "jsx-a11y/no-noninteractive-tabindex": [
        "error",
        { tags: [], roles: ["tabpanel", "group"], allowExpressionValues: true },
      ],
    },
  },
];

On the fixed page, ESLint reports nothing, with one exception comment left in the code. Firefox counts twelve stops, down from fourteen, and each one responds to a key: the Reschedule buttons to Enter and Space, the history to the arrow keys. Of the four tabIndex attributes we started with, two remain: a -1, and a 0 kept for Safari.

Screenshot: Firefox on the fixed Appointments page, with the accessibility inspector open and Show Tabbing Order checked; the three Reschedule buttons keep their numbers, 5 to 7, the help text and the error summary have none, and the vaccine history gets 12.Marker 1. The vaccine history, numbered 12. Marker 2. The first Reschedule button, numbered 5.
Firefox counts twelve stops on the fixed page: the vaccine historymarker 1 gets 12, the first Reschedule buttonmarker 2 keeps its 5, and the help text and error summary get no number.

ESLint reads the components' code. For the page as it appears online, the Includdy scan lists its accessibility issues. For each one, its guided fix shows the faulty HTML beside a compliant component generated by Includdy's AI, to review before it goes into the code.


Share this article

Frequently asked questions

By default, it only checks HTML elements, since it can't know which element a component will render: <Card tabIndex={0}> passes without a word. If the component hands the attribute down to a div, though, the extra stop is really there on the page.

The components setting of jsx-a11y tells the rule that Card renders a div, and the rule then flags it. To see the stop on the page, check “Show Tabbing Order” in Firefox's accessibility inspector: the div gets its number like a real control.

The rule works out the expression without knowing the component's state: it replaces each variable with its name, a string that counts as true. With version 6.10.2 of the plugin, we saw it flag tabIndex={active ? 0 : -1}, read as 0. It lets tabIndex={active ? -1 : 0} through, though, along with tabIndex={i === active ? 0 : -1}: its verdict depends on how the condition is written.

In a composite component, such as a list of options, a group of radio buttons or a menu, each item carries an interactive role (option, radio or menuitem), so the rule stays quiet. For the container that takes focus when Tab lands on such a component, the rule's documentation advises turning the rule off for that one element.

Yes. Its noNoninteractiveTabindex rule, inspired by the jsx-a11y one, is recommended and set to error by default. It describes the same problem: a keyboard stop where no action is expected.

The fixes carry over as they are: a <button> or a link for whatever responds to a click, tabIndex={-1} for whatever a script focuses, and nothing for the rest. On the scrollable region, Biome's useSemanticElements rule also rejects role="group" and suggests a <fieldset>. To keep our code, write two biome-ignore comments, one for each rule.