Maaz Zindani

Loading the index…

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

A modal test fails because the focus trap finds nothing to focus

ErrorYour focus-trap must have at least one container with at least one tabbable node in it at all times

Short answer

focus-trap throws when its container has no element it considers tabbable. In Jest the DOM is jsdom, which has no layout, so tabbable's visibility check can reject every element. Set tabbableOptions.displayCheck to 'none' for tests, give the trap a fallbackFocus element, and make sure the content is rendered before the trap activates.

  • Applies to focus-trap, Jest 29, React 19
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out which modal or dialog the failing test renders, and check whether it contains a button, link or input. A container with none will always throw, in any browser.

    npx jest path/to/failing.test.js --runInBand
  2. 2Match what you see, then jump to its fix

    1. 1The component works in a real browser and fails only under Jest.jsdom cannot answer tabbable's visibility checkFix
    2. 2The dialog content appears after a fetch, a state update or an animation, and the error fires on open.The trap is active while its content is empty or not yet renderedFix
    3. 3A dialog that only shows text, or whose buttons are disabled, throws as soon as it opens.The container has no focusable element and no fallbackFocusFix

What does the error look like?

  • Your focus-trap must have at least one container with at least one tabbable node in it at all times

Cause 1 of 3

jsdom cannot answer tabbable's visibility check

1Check

The libraries state that JSDom is not officially supported. Tabbable's default display check uses DOM APIs such as getClientRects(), which JSDom does not fully implement, so elements a user would see can be judged hidden.

grep -rn "displayCheck\|tabbableOptions" src/ | head

2Fix

For test runs, configure the trap with tabbableOptions.displayCheck set to 'none'. If a wrapper library creates the trap for you, pass the option through the wrapper's own options prop (see its docs).

import { createFocusTrap } from 'focus-trap';
const trap = createFocusTrap(element, {
  tabbableOptions: { displayCheck: process.env.NODE_ENV === 'test' ? 'none' : 'full' },
});

3Verify

Run the test again; the error is gone.

npx jest path/to/failing.test.js

Confirmed by github.com

Did this fix it?

Cause 2 of 3

The trap is active while its content is empty or not yet rendered

1Check

The library throws when the trap's containers hold no tabbable elements, which often happens when the traps are related to elements that appear and disappear dynamically.

grep -rn "activate\|focusTrap" src/ | head

2Fix

Activate the trap only after the content is in the DOM. In the test, wait for the dialog's first button or input to appear before asserting.

import { screen } from '@testing-library/react';
await screen.findByRole('button', { name: /close/i });

3Verify

The test passes without a timing workaround such as a fixed delay.

npx jest path/to/failing.test.js

Confirmed by github.com

Did this fix it?

Cause 3 of 3

The container has no focusable element and no fallbackFocus

1Check

Without fallbackFocus, an error is thrown if the trap contains no elements in its tab order.

grep -rn "fallbackFocus" src/ | head

2Fix

Give the dialog container a negative tabindex and name it as fallbackFocus, so focus has somewhere valid to go.

// <div id="dialog" tabindex="-1"> ... </div>
const trap = createFocusTrap('#dialog', { fallbackFocus: '#dialog' });

3Verify

Open the text-only dialog in the test.

npx jest path/to/failing.test.js

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Keep one helper that builds trap options, so the test-only displayCheck setting lives in one place.
  • Give every dialog at least one real control, such as a close button.
  • Test focus behaviour in a real browser (Playwright or Cypress) as well, since jsdom is not officially supported.

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

Back end

Jest cannot find the jsdom test environment after an upgrade

Config line in play: testEnvironment: 'jsdom'

Since Jest 28 the jsdom environment is a separate package, so a config that says testEnvironment jsdom fails until you install jest-environment-jsdom as a dev dependency.

3 causes, each with a fix

Next step

Want this handled for good?

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