Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

ESLint says an element with role="button" must be focusable

ErrorElements with the 'button' interactive role must be focusable

Short answer

The rule jsx-a11y/interactive-supports-focus flags an element that has an interactive role and a mouse or key handler but cannot receive keyboard focus. The best fix is a native button element. If you must keep the div, add tabIndex={0} plus a key handler so Enter and Space work. tabIndex={-1} only makes it focusable by script.

  • Applies to eslint-plugin-jsx-a11y 6, ESLint 9, React 19
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run ESLint on the one file and read the rule id and line number. The message ends with the rule name, and the element on that line shows which of the causes below applies.

    npx eslint src/components/Toolbar.jsx
  2. 2Match what you see, then jump to its fix

    1. 1The flagged line is <div role="button" onClick={...}> or <span role="button" onClick={...}> with no tabIndexA div or span plays a button but is not in the tab orderFix
    2. 2The element cannot become a button, for example because a library injects its markupThe element must stay a div, so it needs tabIndex and key handlingFix
    3. 3Elements with the 'button' interactive role must be tabbable, while the element already has tabIndex={-1}tabIndex is -1, which is focusable but not tabbableFix
    4. 4The flagged line is <a role="button" onClick={...}> without hrefAn anchor with role="button" has no hrefFix

What does the error look like?

  • Elements with the 'button' interactive role must be focusable
  • Elements with the 'button' interactive role must be tabbable
  • jsx-a11y/interactive-supports-focus

Cause 1 of 4

A div or span plays a button but is not in the tab order

1Check

An element with an interactive role and an event handler must be focusable. A div has no focus behaviour of its own, so keyboard users cannot reach it.

grep -rn 'role="button"' src

2Fix

Replace it with a real button element. The rule's documentation lists a button as inherently focusable, so the error goes away and the element joins the tab order.

// before
<div role="button" onClick={save}>Save</div>

// after
<button onClick={save}>Save</button>

3Verify

Run ESLint on the file again. The error is gone, and Tab now stops on the control.

npx eslint src/components/Toolbar.jsx

Confirmed by github.com

Did this fix it?

Cause 2 of 4

The element must stay a div, so it needs tabIndex and key handling

1Check

tabIndex={0} puts the element in the tab order and clears the lint error, but a focusable role="button" element also has to react to the keyboard. The ARIA button pattern says Space and Enter activate a button.

grep -rn 'role="button"' src | grep -v onKeyDown

2Fix

Add tabIndex={0} and a key handler for Enter and Space.

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

3Verify

Tab to the element and press Enter and Space. Then run ESLint again.

npx eslint src/components/Toolbar.jsx

Confirmed by w3.org

Did this fix it?

Cause 3 of 4

tabIndex is -1, which is focusable but not tabbable

1Check

The rule documents an option named tabbable. Roles listed there, with button among them in the documented example, need a place in the tab ring, which means tabIndex 0. A value of -1 is only for items inside a composite widget such as a menu.

grep -rn 'tabIndex={-1}' src

2Fix

Use tabIndex={0} for a standalone button. Keep -1 only for the non-active items of a menu, tab list or similar group that you move through with arrow keys.

<div role="button" tabIndex={0} onClick={save} onKeyDown={onKey}>Save</div>

3Verify

Run ESLint on the file.

npx eslint src/components/Toolbar.jsx

Confirmed by github.com

Did this fix it?

Cause 4 of 4

An anchor with role="button" has no href

1Check

An anchor without an href is not focusable, so the role does not rescue it. The rule's own failing example is exactly this.

grep -rn '<a ' src | grep -v href

2Fix

If it navigates, give it a real href. If it runs an action, make it a button.

// navigation
<a href="/next">Next page</a>

// action
<button type="button" onClick={showNextPage}>Next page</button>

3Verify

Run ESLint on the file.

npx eslint src/components/Toolbar.jsx

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Start from native elements: button for actions, a with href for navigation, input for fields. Reach for role only when no native element exists.
  • Keep the jsx-a11y recommended config on in CI, so a clickable div fails the build and never reaches review.
  • After any change to a custom control, press Tab, Enter and Space on it in the browser once.
  • Do not silence the rule with an eslint-disable comment; the keyboard users it protects are real.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.