ADA Compliance Professionals

    Unique iframe titles: fix and test

    Last updated:

    Who it helps:
    Blind
    Cognitive
    Standard:
    WCAG 2.2 Level A

    Related Guides

    Frames and iframes must have unique, descriptive title attributes

    Give every frame and iframe a unique, meaningful title attribute. This appears wherever embedded documents or widgets are used, such as videos, maps, chat tools, or dashboards. It primarily affects screen reader users who rely on these titles to understand and navigate embedded content.

    Why It Matters

    Screen reader users often open a list of frames on a page and jump directly to the one they need. If titles are missing or repeated, that list becomes confusing and slows navigation.

    A clear title sets expectations before the user enters the embedded content. This helps users with low vision, cognitive disabilities, or anyone who depends on assistive technology to maintain orientation.

    Providing a descriptive title aligns with WCAG 2.2 guidance for titling content (SC 2.4.2) and common techniques for frames.

    Common Causes

    • No title attribute on iframes added by templates or CMS widgets
    • Duplicate titles used across multiple embeds on the same page
    • Generic titles like "frame", "content", or "widget"
    • Third‑party embed codes pasted without adding a title
    • Titles that describe technology or URLs instead of the frame’s purpose
    • Inner document <title> missing or mismatched with the iframe’s title

    How to Fix

    1. Add a title attribute to every <iframe> and <frame>.
      • Make it unique on the page.
      • Keep it concise (recommendation: 3–8 words) and purpose‑focused.
      • Example patterns: "Store locator map", "Video: Product demo", "Support FAQ".
    2. Match the inner document title when possible.
      • If you control the framed document, set its <title> to the same text as the iframe’s title. Some screen readers will announce the inner document title instead of the attribute.
    3. Avoid generic or duplicated text.
      • Do not use "frame", "embed", or repeated labels like "Widget".
    4. Handle decorative or tracking iframes.
      • If an iframe has no user‑facing purpose, hide it from assistive tech (aria-hidden="true"). Ensure no focusable elements exist inside.
    5. Localize titles.
      • Provide titles in the page’s language. If the embedded content serves another locale, ensure the visible purpose is still clear.
    6. Bake titles into components and templates.
      • For reusable components that render iframes, add a required prop or field to set unique titles at use time.

    How to Test

    Keyboard check

    • Tab through the page and confirm focus does not unexpectedly move into decorative or hidden iframes.
    • Interactive content inside meaningful iframes must be keyboard accessible.

    Screen reader check

    • NVDA/JAWS (Windows): Open the list of frames and verify each one is present with a unique, descriptive name.
    • VoiceOver (macOS/iOS): Use the rotor (macOS) or rotor-like menus (iOS) to find frames; ensure names are clear and unique.
    • TalkBack (Android): Navigate to the embedded region; confirm it is announced with its title.

    Accessibility tree check

    • Inspect the iframe in browser devtools. Confirm the accessible name equals the title, and that duplicates do not exist.

    Automated checks

    • Run tools such as axe, WAVE, or Lighthouse and verify the "Frame must have a title" rule passes; review any duplicates manually.

    Good Example

    HTML
    <!-- Host page -->
<section>
  <h2>Help Center</h2>
  <iframe src="/help/faq.html" title="Support FAQ"></iframe>
</section>

<section>
  <h2>Demo</h2>
  <iframe src="https://www.example.com/embed/demo" title="Video: Product demo"></iframe>
</section>

<!-- Inside /help/faq.html (framed document) -->
!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Support FAQ</title>
</head>
<body>
  <!-- FAQ content -->
</body>
</html>

    Bad Example

    HTML
    <!-- Missing and duplicate titles -->
<iframe src="/help/faq.html"></iframe>
<iframe src="/help/contact.html" title="Content"></iframe>
<iframe src="/embed/widget" title="Content"></iframe>

<!-- Decorative iframe exposed to AT -->
<iframe src="/analytics/pixel" title="frame"></iframe>

    Quick Checklist

    • Every frame and iframe has a title attribute
    • Titles are unique on the page and describe the frame’s purpose
    • Titles are short and user‑focused (avoid jargon, URLs, or tech terms)
    • Inner document <title> matches the iframe title where feasible
    • Decorative/utility iframes are hidden from assistive tech (aria-hidden="true")
    • Third‑party embeds are given appropriate titles in the host page
    • Automated checks pass and manual screen reader review confirms clarity