The <iframe> Element

Technical Summary

Definition / Categories

Item	Normative organization
Meaning	Represents the content navigable containing the embedded content
Categories	Flow content, Phrasing content, Embedded content, Interactive content, and Palpable content
Context	Where embedded content is expected
Content model	Nothing
Main content attributes	src, srcdoc, name, sandbox, allow, allowfullscreen, width, height, referrerpolicy, and loading
DOM interface	HTMLIFrameElement, including src, srcdoc, name, sandbox, allow, referrerPolicy, loading, contentDocument, and contentWindow

A content navigable is the Web Platform container used to load the iframe's child document. The DOM element visible to the parent and the active Document inside the child navigable are distinct objects.

src, srcdoc, and the initial document

When src is present, its value is parsed as a URL relative to the parent Document and the iframe's content navigable is navigated. When srcdoc is present, the user agent constructs an about:srcdoc Document from it and gives it priority over src.

State	Boundary to inspect
srcdoc present	Constructs a srcdoc document whose URL is treated as about:srcdoc
srcdoc absent, valid src	Navigates the child navigable to the resolved URL
No src on initial insertion or parsing fails	The initial about:blank Document can remain active
Both src and srcdoc	Processes srcdoc; src is not used at the same time as the active fallback

<iframe
  title="Generated preview"
  sandbox
  srcdoc="&lt;h1&gt;Preview&lt;/h1&gt;&lt;p&gt;Separate document&lt;/p&gt;">
</iframe>

HTML in the attribute is interpreted in two stages: by the outer HTML parser and then as the srcdoc document. Quotation marks, ampersands, and script-containing strings therefore need an explicit Trusted Types, CSP, and sanitization policy.

Navigation, load, and the DOM interface

When iframe attributes are inserted, changed, or removed, the user agent can run the iframe attributes processing steps and navigate the child navigable. When loading completes, a load event is fired at the iframe. A load event is not evidence that the content is trustworthy, correct, or readable by the parent DOM.

const frame = document.querySelector('#preview');

frame.addEventListener('load', () => {
  console.log(frame.contentWindow);
});

// Whether contentDocument can be read depends on origin and other conditions.

contentDocument and contentWindow are exposed by the DOM interface, but they do not mean that a parent can freely read or write a cross-origin child document. Same-origin policy, sandbox opaque origins, CSP, and COEP are separate boundaries that may need to be evaluated together.

sandbox, origin, and permissions

When the sandbox attribute is present, additional sandboxing restrictions apply to the iframe's content. With an empty sandbox value, scripts, forms, popups, top-level navigation, and other capabilities are restricted. Tokens can selectively re-enable capabilities.

Setting	Main boundary	Important condition
sandbox	Enables additional restrictions	Even an empty value enables restrictions
allow-scripts	Allows script execution	Other restrictions remain unless separately re-enabled
allow-same-origin	Uses the real origin rather than an opaque origin	With scripts and same-origin content, it can provide a path to remove the sandbox
allow-forms and similar tokens	Re-enable forms, popups, or top navigation as applicable	Choose only the capabilities required by the embedded application

Giving same-origin content both allow-scripts and allow-same-origin can allow the content to remove the sandbox in some situations, so this combination is not a strong isolation design. Separating the origin that serves hostile content is an additional security measure rather than a replacement for careful sandbox configuration.

allow, referrerpolicy, and loading

Attribute	Role	Different from
allow	Specifies Permissions Policy applied to the iframe contents	Not the script or origin restrictions provided by sandbox
referrerpolicy	Controls the referrer policy for fetches initiated by the element	Does not grant the parent DOM access to the child
loading	Participates in deciding whether navigation is lazy-loaded	Is a loading hint, not a security or permission boundary
allowfullscreen	Relates to Fullscreen API use by the iframe contents	Fullscreen conditions, Permissions Policy, and user activation still matter

Adding an attribute does not guarantee that a capability will work. HTTP Permissions Policy, CSP, sandboxing, user activation, and user-agent behavior can all contribute conditions.

Accessibility

HTML-AAM gives iframe no corresponding WAI-ARIA role, while defining platform-specific mappings such as an internal frame. The iframe's accessible name can be computed from aria-label, aria-labelledby, or title. The embedded Document has its own naming condition based on its own title element.

<iframe
  src="https://example.com/payment"
  title="Secure payment form"
></iframe>

The parent's title does not replace checking the embedded service itself. Record the child Document's title, headings, keyboard behavior, focus, announcements, and error presentation separately from the parent Accessibility Tree.

Fact / Evidence

Normative claims about the element and its processing model are separated from browser implementation, WPT, and accessibility observations.

Evidence

1. HTML Standard: The iframe element — categories, content model, attributes, content navigables, src/srcdoc, sandboxing, navigation, load, and the DOM interface
2. Permissions Policy: iframe allow attribute — the iframe policy container and delegated policy
3. HTML Accessibility API Mappings: iframe — platform role mappings and accessible-name computation
4. Web Platform Tests: the-iframe-element — entry point for tests related to iframe attributes, navigation, sandboxing, loading, and DOM APIs

Implementation Evidence

Normative processing is recorded separately from browser observations of navigation, load, DOM access, sandboxing, and accessibility trees. A dedicated fixture was run in Chrome 153.0.0.0 on Windows NT 10.0, and only the observed range is registered as partial evidence.

Executed fixture: iframe-v1 checked srcdoc precedence, initial about:blank, srcdoc mutation and load, same-origin contentDocument, the sandbox event-origin boundary, and titled accessibility-tree entries. The execution record is stored at docs/atlas/iframe-v1-results-2026-09-19.md.

Iframe rendering, load behavior, DOM access, origin, sandboxing, Permissions Policy, and accessibility-tree exposure can depend on the URL, HTTP headers, parent/child origins, attributes, user agent, and OS. A single-environment observation will not be registered as universal behavior.

Coverage / Open Issues

• CoveredMeaning, categories, context, content model, major attributes, and the HTMLIFrameElement entry points
• CoveredNormative entry points for src/srcdoc precedence, initial about:blank, content navigables, navigation, and load
• CoveredSandboxing, allow, referrerpolicy, loading, and accessible-name source locations
• PartialChrome 153 observations of srcdoc precedence, initial about:blank, srcdoc mutation and load, same-origin DOM access, sandbox event origin, attribute reflection, and the accessibility tree
• OpenFirefox/Safari comparison of srcdoc, load, attribute changes, sandboxing, loading, and contentDocument, plus Chrome's actual lazy-loading behavior
• OpenInteractions among cross-origin behavior, CSP, COEP/CORP, Permissions Policy, postMessage, window.name, and navigation
• OpenIndividual WPT results, complete HTML-AAM platform mappings, assistive-technology observations, compatibility, and Expert-gap Review

This is initial coverage. It records normative entry points and evidence boundaries without claiming identical results across browsers, HTTP-header configurations, origin setups, embedded services, or assistive technologies.

Related surface

For a beginner-friendly explanation of embedding, title, sandbox, srcdoc, and the difference from links, see the iframe element page in Yugien. For navigation boundaries, see the a element; for script fetching and execution, see the script element; and for form submission, see the form element.