All rules

Sheath rule

a11y-require-frame-title

Iframe and frame elements must have an accessible name describing their content.
Package
Core
Category
Accessibility
Default severity
error by default
Auto-fix
Manual fix

#Why

Screen readers use the accessible name to describe the purpose of an iframe. HTML-AAM permits that name to come from aria-labelledby, aria-label, or title, in that order.

#Examples

#Bad

<!-- Missing title -->

<iframe src="https://example.com/widget"></iframe>



<!-- Empty title -->

<iframe src="https://maps.google.com/embed" title=""></iframe>



<!-- Frame without title (older HTML) -->

<frame src="navigation.html">

#Good

<!-- Descriptive title -->

<iframe src="https://example.com/widget" title="Customer Support Chat Widget"></iframe>



<!-- Map embed with title -->

<iframe src="https://maps.google.com/embed?q=..." title="Google Map showing our office location"></iframe>



<!-- Video embed -->

<iframe src="https://youtube.com/embed/abc123" title="Product Demo Video"></iframe>



<!-- ARIA naming alternatives -->

<iframe src="chart.html" aria-label="Quarterly sales chart"></iframe>

<span id="payment-title">Secure payment form</span>

<iframe src="payment.html" aria-labelledby="payment-title"></iframe>



<!-- Hidden iframe doesn't need title -->

<iframe src="tracking.html" aria-hidden="true"></iframe>



<!-- Frame with title -->

<frame src="navigation.html" title="Site Navigation">

#Notes

  • The accessible name should describe the frame's purpose, not just "iframe"
  • Decorative or tracking iframes can use aria-hidden="true" to skip the title requirement
  • The requirement also applies to <frame> elements from older HTML versions
  • Consider whether an iframe is the best solution - sometimes native content is more accessible
  • Opaque attribute spreads such as {{ $attributes }} make the final title unknowable and are not checked. Every explicit Blade branch exposed to the accessibility tree must have an accessible name

#References

#Related Rules