iframe title: naming embedded frames for screen readers

What an iframe title is

An iframe is a separate document embedded in the page. A screen reader user reaching one hears its title, decides whether to enter it, and either steps inside or moves past. With no title the announcement is “frame”, and the only way to find out what is in it is to go in.

The title attribute supplies that name. aria-label and aria-labelledby do the same job.

What squirrel checks

One check, frame-title, at severity error. It covers every <iframe> and <frame>, skipping any with role="presentation" or role="none" and any hidden from the accessibility tree (see below).

• Fail when the element has no non-empty title, no non-empty aria-label and no aria-labelledby. Report message: N iframe(s) without title attribute. Items are identified by name first, then id, then the hostname taken from the src, as iframe (www.youtube.com). Up to ten are shown with a count of the rest.
• Pass with N iframe(s) have title attributes.
• Info with No iframes found.

Hidden iframes

An iframe out of the accessibility tree has nothing to announce, so it is not reported: one with the hidden attribute (except hidden="until-found"), aria-hidden="true" on itself or an ancestor, display: none on itself or an ancestor (set inline or by a <style> rule squirrel can decide), or inside a closed <dialog> or an unopened popover. The pass message then reads “in the accessibility tree” and the count of skipped elements is kept in hiddenWithoutName. It still needs a name before it is shown.

squirrel reads the markup, inline styles and the page’s <style> blocks, the same way as form-labels; see form-labels for what it can and cannot decide. External stylesheets are not read. An unnamed iframe that carries a no-js class, itself or on an ancestor other than <html>, is reported as unconfirmed on a page with an external stylesheet or an @import, because a theme usually hides that fallback once JavaScript runs. One a style may hide but squirrel cannot settle (a pseudo-class, a media query, a page that also loads an external stylesheet) is unconfirmed too. Report message: N iframe(s) without title attribute may be hidden by a style (unconfirmed), under the check name frame-title-unconfirmed.

Findings are labelled iframe even when the element is a legacy <frame>.

Elements inside <noscript> are skipped: a browser with scripting enabled reads <noscript> content as plain text, so nothing in it loads or renders. See content inside noscript.

How to fix it

<iframe src="https://www.youtube.com/embed/xyz"
        title="Product demo, 3 minutes"></iframe>

Describe the content, not the technology. Most embed snippets ship title="YouTube video player", which names the vendor rather than the video, and every embed on the site ends up with the same name.

An iframe carrying an ad or a tracking pixel still needs a name. “Advertisement” is a reasonable one. squirrel also skips frames marked aria-hidden="true" or role="presentation", so a genuinely presentational frame can be excluded that way.

Enable / disable

Disable this rule

[rules]
disable = ["a11y/frame-title"]

Disable all Accessibility rules

[rules]
disable = ["a11y/*"]

Enable only this rule

[rules]
enable = ["a11y/frame-title"]

enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.

Related rules

• a11y/video-captions: recognizes a YouTube, Vimeo or Wistia iframe and asks you to confirm captions in the player.
• a11y/object-alt: the same naming requirement for <object>.
• a11y/aria-dialog-name: another container announced by name before it is entered.
• a11y/aria-hidden-focus: focusable controls inside a hidden region. Frames only count there when they carry an explicit tabindex.

Accessibility findings ship in every audit next to the SEO, performance and agent experience rules. See Website security scan with AI for how an agent works through a report.

References

• The iframe element, MDN
• H64: Using the title attribute of the iframe element, W3C
• Understanding SC 4.1.2 Name, Role, Value, W3C

Check your site

Run squirrel audit https://example.com and open the Accessibility section of the report. Each unnamed frame is listed by name, id or the host it loads from. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.