Frames Must Not Block Focus: How to Fix It

The axe-core rule "Frames must not block focus" (rule ID frame-focusable-content) flags a common but easy to miss accessibility defect. When a frame is taken out of the keyboard tab order while it still contains things people need to click or type into, those controls become unreachable for anyone who navigates without a mouse. This guide explains what the rule checks, why it matters, how to diagnose it, and exactly how to fix it.

What the rule checks

The axe-core frame-focusable-content rule inspects every <frame> and <iframe> on the page. For each one, it looks at two things: does the frame carry tabindex="-1", and does the document inside that frame contain focusable elements such as links, buttons, form inputs, or other interactive controls. If both conditions are true, the check fails.

The logic is deliberately narrow. A frame with tabindex="-1" that holds only static content, such as a decorative image or a block of read-only text, does not violate the rule. The problem only exists when interactive content is locked behind a frame that the keyboard can no longer enter.

How tabindex=-1 on a frame blocks focus

A negative tabindex value removes an element from the sequential tab order. On most elements that simply means pressing Tab will skip past it. On a frame, the effect is larger: the browser is prevented from redirecting focus into the frame's document at all. Every focusable control inside, no matter how many there are, is skipped along with the frame itself.

So a single attribute on the wrapping <iframe> can hide an entire embedded form, a payment widget, an interactive map, or a third-party booking tool from keyboard navigation. The content is still painted on screen and looks perfectly usable to a sighted mouse user, which is exactly why the issue slips through manual review.

Why keyboard access matters

This rule maps to WCAG Success Criterion 2.1.1 Keyboard (Level A), which requires that all functionality be operable through a keyboard interface. People who use a keyboard instead of a mouse include those with motor impairments, screen reader users, people using switch devices, and anyone whose pointing device has failed. When focusable content is trapped inside a frame with tabindex="-1", those users cannot reach it, so the criterion fails.

Depending on the content, the same defect can also contribute to failures of SC 2.4.3 Focus Order. Beyond compliance, a checkout button or contact form that cannot receive focus is a direct loss of conversions and a real barrier for a measurable share of your visitors.

How to diagnose

Start with the automated report. Axe-core names the rule frame-focusable-content and points to the offending frame in the results. Open your browser developer tools, inspect the flagged node, and confirm it is a <frame> or <iframe> carrying tabindex="-1".

Next, confirm the frame really contains interactive content. View the framed document and look for links, buttons, inputs, selects, or anything with its own positive or zero tabindex. Then do the manual test that matters most: load the page, put your mouse aside, and press Tab repeatedly. If the tab ring never moves into the embedded content, you have reproduced the problem exactly as a keyboard user would experience it.

How to fix it

The fix is to remove the focus-blocking attribute. Delete tabindex="-1" from the frame so the browser handles focus naturally and lets keyboard users tab into the embedded controls. You do not need to add a positive value; absence of the attribute is the correct state for a frame with interactive content.

<!-- Bad: keyboard users cannot reach the form inside -->
<iframe src="/booking-widget.html" title="Booking" tabindex="-1"></iframe>

<!-- Good: browser manages focus, controls are reachable -->
<iframe src="/booking-widget.html" title="Booking"></iframe>

After removing the attribute, run the Tab test again to confirm focus now enters the frame and reaches each interactive element in a sensible order. Keep the descriptive title attribute in place, since that helps screen reader users understand what the frame contains. If the frame genuinely holds no interactive content and you added tabindex="-1" on purpose, the correct fix is instead to make sure the framed document truly has nothing focusable, at which point the rule will pass on its own.

Common mistakes

The most frequent mistake is reaching for tabindex="-1" on a frame to "tidy up" the tab order, without realizing it cuts off everything inside. Another is assuming the attribute is harmless because the content still displays normally; visibility and keyboard reachability are separate things. A third is adding the attribute to suppress a focus outline or an unwanted tab stop on the frame element, when the real solution is to address the styling or the inner control directly. Finally, teams sometimes copy a third-party embed snippet that ships with tabindex="-1" baked in and never audit it; always check vendor embed code for this attribute before shipping.

FAQ