• June 26, 2025

Preventing Accessibility Issues with Focusable Content Inside Frames

Rule ID: frame-focusable-content
Ruleset: axe-core 4.10
User Impact: Serious
Guidelines: WCAG 2.1 (A), WCAG 2.0 (A), WCAG 2.2 (A), Trusted Tester, EN 301 549

How to Fix the Problem

When using <iframe> elements that contain interactive or focusable content (like buttons, links, or input fields), ensure the frame is keyboard-accessible. This can be controlled using the tabindex attribute appropriately.

✅ Correct Markup Examples

1. Allowing Keyboard Access:

   html

   KopierenBearbeiten

   <iframe
srcdoc="<button>Click me</button>"
tabindex="0"
title="My frame is an iframe"
></iframe>


   Use tabindex="0" when the content inside the iframe needs to be navigable by keyboard users. This enables proper focus redirection into the iframe content.

2. Disabling Keyboard Focus When Appropriate:

   html

   KopierenBearbeiten

   <iframe
srcdoc="<p>Hello world</p>"
tabindex="-1"
title="My frame is an iframe"
></iframe>


   Use tabindex="-1" only if the iframe does not contain any interactive or focusable content and does not require keyboard scrolling or interaction.

❌ Incorrect Markup Example

In this example, tabindex="-1" prevents keyboard users from reaching the interactive button inside the iframe, making it inaccessible.

Best Practice:

Avoid using tabindex="-1" on frames altogether unless you are absolutely sure the content inside does not and will not require keyboard interaction. Future changes or dynamic content might unintentionally introduce focusable elements, leading to accessibility issues.

Why it Matters

When a frame includes focusable or interactive elements, a negative tabindex on the frame (tabindex="-1") prevents keyboard users from navigating into it. This effectively hides content from users relying on keyboard navigation or assistive technology, such as screen readers or switch devices.

Moreover, if the frame contains scrollable regions, users may not be able to scroll using the keyboard, leading to a frustrating and incomplete experience. Ensuring keyboard accessibility is essential for users with motor disabilities or visual impairments who rely on the keyboard instead of a mouse.

Rule Description

The <frame> and <iframe> elements that contain focusable content (such as buttons, links, form fields, etc.) must not have tabindex="-1". Doing so makes this content unreachable for keyboard and assistive technology users.

The Algorithm (in simple terms)

The check looks for any <iframe> or <frame> elements that:

1. Contain focusable or interactive content.

2. Are marked with tabindex="-1".

If both conditions are true, the rule fails. The goal is to ensure that content inside a frame is not hidden from keyboard focus.