probeo

How to give an iframe an accessible name?

frame-title page

The issue

A frame with no name is announced as a frame and nothing more. A screen reader user moving through the page meets an embedded video, a map, a payment form and a chat widget, each announced the same way, and has to enter each one to find out what it is. Two frames with the same title and different content leave them guessing in the same way.

The cause is a missing or repeated name. An <iframe> gets its name from its title attribute, or from aria-label or aria-labelledby. Embed codes copied from video hosts, maps and form tools often leave it out. WCAG 4.1.2 requires every user interface component to have a name, and 2.4.1 ties frame titles to finding your way through a page.

Scope

Two rules cover frames:

  • frame-title checks each visible <iframe> and <frame>. It passes with a non-empty title, aria-label or aria-labelledby. Frames with role="none" or role="presentation" are skipped.
  • frame-title-unique compares the titles of visible frames, ignoring case. Two frames with the same title and different src are both reported. Frames with the same title and the same src pass.

Frames hidden with hidden, aria-hidden="true", or an inline display: none or visibility: hidden are skipped by both.

How to check you have it

  • In probeo: the page reports frame-title, “Frames must have an accessible name”, with serious impact, and frame-title-unique, “Frames should have a unique title attribute”, also serious. frame-title maps to WCAG 4.1.2 and 2.4.1; frame-title-unique is best practice.
  • By hand: view the page source, search for <iframe, and read each one’s title. Each should say what the frame contains, and no two different frames should share one.
  • With a tool: axe DevTools reports both rules by the same names.

The fix

Give every iframe a title that names what it contains.

Name the content, not the technology: “Product demo video”, “Map of the Denver office” and “Newsletter sign-up form” all tell someone whether to go in. Where a page has two similar frames, make the titles differ by what differs between them.

<iframe src="https://www.youtube-nocookie.com/embed/abc123"
        title="Product demo: setting up your first site"></iframe>

If the frame shows nothing a person needs, such as a tracking frame, hide it from assistive technology with aria-hidden="true" and make sure it holds nothing focusable.

Done when: every visible frame has a name that says what it holds, no two different frames share a title, and the check above comes back clean.

Do not

  • Do not use titles like “iframe”, “frame” or “embed”, which repeat what the screen reader already says.
  • Do not reuse one title across different embeds on the same page.
  • Do not hide a frame that contains content or controls people need.

FAQ

Is aria-label as good as title?

For frame-title, yes: probeo accepts title, aria-label or aria-labelledby. The uniqueness check reads only title, so a page relying on aria-label alone isn’t compared for duplicates.

Does the page inside the frame need its own title?

Yes, as a separate matter. The document inside the frame has its own <title>, and it should be meaningful too. The frame’s title is what people hear before they go in.

What about third-party widgets that inject their own iframe?

They are checked like any other frame when they are in the page as probeo captures it. Many embed tools let you set the title in their configuration; if one doesn’t, set it on the iframe after it loads, or ask the vendor.

Which product detects this

Probeo checks this on every page of your site as part of Site Clarity. This page explains one instance; the product tells you every page that has it.