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


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.
Marker 1. The help text, numbered 8. Marker 2. The error summary, numbered 9. Marker 3. The first Reschedule control, numbered 5.
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.
Marker 1. The Reschedule control on the card.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.
Marker 1. The error summary, at the top of the form.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.
Marker 1. The help text, under the card.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.
| Browser | Scrollable region with no tabindex and nothing focusable inside |
|---|---|
| Chrome, since version 132 | Reached with Tab |
| Firefox | Reached with Tab |
| Safari | Never 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.
Marker 1. The region that scrolls around the vaccine table.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.
Marker 1. The vaccine history, numbered 12. Marker 2. The first Reschedule button, numbered 5.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.


