HTML

[Exposed=Window]
interface HTMLIFrameElement : HTMLElement {
  [HTMLConstructor] constructor();

  [CEReactions, ReflectURL] attribute USVString src;
  [CEReactions] attribute (TrustedHTML or DOMString) srcdoc;
  [CEReactions, Reflect] attribute DOMString name;
  [SameObject, PutForwards=value, Reflect] readonly attribute DOMTokenList sandbox;
  [CEReactions, Reflect] attribute DOMString allow;
  [CEReactions, Reflect] attribute boolean allowFullscreen;
  [CEReactions, Reflect] attribute DOMString width;
  [CEReactions, Reflect] attribute DOMString height;
  [CEReactions] attribute DOMString referrerPolicy;
  [CEReactions] attribute DOMString loading;
  readonly attribute Document? contentDocument;
  readonly attribute WindowProxy? contentWindow;
  Document? getSVGDocument();

  // also has obsolete members
};

The iframe element represents its content navigable.

The src attribute gives the URL of a page that the element's content navigable is to contain. The attribute, if present, must be a valid non-empty URL potentially surrounded by spaces. If the itemprop attribute is specified on an iframe element, then the src attribute must also be specified.

Element/iframe#attr-srcdoc

Support in all current engines.

Firefox25+Safari6+Chrome20+

Opera?Edge79+

Edge (Legacy)?Internet ExplorerNo

Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android?

The srcdoc attribute gives the content of the page that the element's content navigable is to contain. The value of the attribute is used to construct an iframe srcdoc document, which is a Document whose URL matches about:srcdoc.

The srcdoc attribute, if present, must have a value using the HTML syntax that consists of the following syntactic components, in the given order:

Any number of comments and ASCII whitespace.
Optionally, a DOCTYPE.
Any number of comments and ASCII whitespace.
The document element, in the form of an html element.
Any number of comments and ASCII whitespace.

The above requirements apply in XML documents as well.

Here a blog uses the srcdoc attribute in conjunction with the sandbox attribute described below to provide users of user agents that support this feature with an extra layer of protection from script injection in the blog post comments:

<article>
 <h1>I got my own magazine!</h1>
 <p>After much effort, I've finally found a publisher, and so now I
 have my own magazine! Isn't that awesome?! The first issue will come
 out in September, and we have articles about getting food, and about
 getting in boxes, it's going to be great!</p>
 <footer>
  <p>Written by <a href="/users/cap">cap</a>, 1 hour ago.
 </footer>
 <article>
  <footer> Thirteen minutes ago, <a href="/users/ch">ch</a> wrote: </footer>
  <iframe sandbox srcdoc="<p>did you get a cover picture yet?"></iframe>
 </article>
 <article>
  <footer> Nine minutes ago, <a href="/users/cap">cap</a> wrote: </footer>
  <iframe sandbox srcdoc="<p>Yeah, you can see it <a href=&quot;/gallery?mode=cover&amp;amp;page=1&quot;>in my gallery</a>."></iframe>
 </article>
 <article>
  <footer> Five minutes ago, <a href="/users/ch">ch</a> wrote: </footer>
  <iframe sandbox srcdoc="<p>hey that's earl's table.
<p>you should get earl&amp;amp;me on the next cover."></iframe>
 </article>

Notice the way that quotes have to be escaped (otherwise the srcdoc attribute would end prematurely), and the way raw ampersands (e.g. in URLs or in prose) mentioned in the sandboxed content have to be doubly escaped — once so that the ampersand is preserved when originally parsing the srcdoc attribute, and once more to prevent the ampersand from being misinterpreted when parsing the sandboxed content.

Furthermore, notice that since the DOCTYPE is optional in iframe srcdoc documents, and the html, head, and body elements have optional start and end tags, and the title element is also optional in iframe srcdoc documents, the markup in a srcdoc attribute can be relatively succinct despite representing an entire document, since only the contents of the body element need appear literally in the syntax. The other elements are still present, but only by implication.

In the HTML syntax, authors need only remember to use U+0022 QUOTATION MARK characters (") to wrap the attribute contents and then to escape all U+0026 AMPERSAND (&) and U+0022 QUOTATION MARK (") characters, and to specify the sandbox attribute, to ensure safe embedding of content. (And remember to escape ampersands before quotation marks, to ensure quotation marks become " and not &quot;.)

In XML the U+003C LESS-THAN SIGN character (<) needs to be escaped as well. In order to prevent attribute-value normalization, some of XML's whitespace characters — specifically U+0009 CHARACTER TABULATION (tab), U+000A LINE FEED (LF), and U+000D CARRIAGE RETURN (CR) — also need to be escaped. [XML]

If the src attribute and the srcdoc attribute are both specified together, the srcdoc attribute takes priority. This allows authors to provide a fallback URL for legacy user agents that do not support the srcdoc attribute.

The iframe HTML element post-connection steps, given insertedNode, are:

Create a new child navigable for insertedNode.
If insertedNode has a sandbox attribute, then parse the sandboxing directive given the attribute's value and insertedNode's iframe sandboxing flag set.
Process the iframe attributes for insertedNode, with initialInsertion set to true.

The iframe HTML element removing steps, given removedNode, are to destroy a child navigable given removedNode.

This happens without any unload events firing (the element's content document is destroyed, not unloaded).

Although iframes are processed while in a shadow tree, per the above, several other aspects of their behavior are not well-defined with regards to shadow trees. See issue #763 for more detail.

Whenever an iframe element with a non-null content navigable has its srcdoc attribute set, changed, or removed, the user agent must process the iframe attributes.

Similarly, whenever an iframe element with a non-null content navigable but with no srcdoc attribute specified has its src attribute set, changed, or removed, the user agent must process the iframe attributes.

To process the iframe attributes for an element element, with an optional boolean initialInsertion (default false):

If element's srcdoc attribute is specified, then:
1. Set element's current navigation was lazy loaded boolean to false.
2. If the will lazy load element steps given element return true, then:
  1. Set element's lazy load resumption steps to the rest of this algorithm starting with the step labeled navigate to the srcdoc resource.
  2. Set element's current navigation was lazy loaded boolean to true.
  3. Start intersection-observing a lazy loading element for element.
  4. Return.
3. Navigate to the srcdoc resource: Navigate an iframe or frame given element, about:srcdoc, the empty string, and the value of element's srcdoc attribute.
  
  The resulting Document must be considered an iframe srcdoc document.
Otherwise:
1. Let url be the result of running the shared attribute processing steps for iframe and frame elements given element and initialInsertion.
2. If url is null, then return.
3. If url matches about:blank and initialInsertion is true, then:
  1. Run the iframe load event steps given element.
  2. Return.
4. Let referrerPolicy be the current state of element's referrerpolicy content attribute.
5. Set element's current navigation was lazy loaded boolean to false.
6. If the will lazy load element steps given element return true, then:
  1. Set element's lazy load resumption steps to the rest of this algorithm starting with the step labeled navigate.
  2. Set element's current navigation was lazy loaded boolean to true.
  3. Start intersection-observing a lazy loading element for element.
  4. Return.
7. Navigate: Navigate an iframe or frame given element, url, and referrerPolicy.

The shared attribute processing steps for iframe and frame elements, given an element element and a boolean initialInsertion, are:

Let url be the URL record about:blank.
If element has a src attribute specified, and its value is not the empty string, then:
1. Let maybeURL be the result of encoding-parsing a URL given that attribute's value, relative to element's node document.
2. If maybeURL is not failure, then set url to maybeURL.
If the inclusive ancestor navigables of element's node navigable contains a navigable whose active document's URL equals url with exclude fragments set to true, then return null.
If url matches about:blank and initialInsertion is true, then perform the URL and history update steps given element's content navigable's active document and url.

This is necessary in case url is something like about:blank?foo. If url is just plain about:blank, this will do nothing.
Return url.

To navigate an iframe or frame given an element element, a URL url, a referrer policy referrerPolicy, an optional string-or-null srcdocString (default null), and an optional boolean initialInsertion (default false):

Let historyHandling be "auto".
If element's content navigable's active document is not completely loaded, then set historyHandling to "replace".
If element is an iframe, then set element's pending resource-timing start time to the current high resolution time given element's node document's relevant global object.
Navigate element's content navigable to url using element's node document, with historyHandling set to historyHandling, referrerPolicy set to referrerPolicy, documentResource set to srcdocString, and initialInsertion set to initialInsertion.

Each Document has an iframe load in progress flag and a mute iframe load flag. When a Document is created, these flags must be unset for that Document.

To run the iframe load event steps, given an iframe element element:

Assert: element's content navigable is not null.
Let childDocument be element's content navigable's active document.
If childDocument has its mute iframe load flag set, then return.
If element's pending resource-timing start time is not null, then:
1. Let global be element's node document's relevant global object.
2. Let fallbackTimingInfo be a new fetch timing info whose start time is element's pending resource-timing start time and whose response end time is the current high resolution time given global.
3. Mark resource timing given fallbackTimingInfo, url, "iframe", global, the empty string, a new response body info, and 0.
4. Set element's pending resource-timing start time to null.
Set childDocument's iframe load in progress flag.
Fire an event named load at element.
Unset childDocument's iframe load in progress flag.

This, in conjunction with scripting, can be used to probe the URL space of the local network's HTTP servers. User agents may implement cross-origin access control policies that are stricter than those described above to mitigate this attack, but unfortunately such policies are typically not compatible with existing web content.

If an element type potentially delays the load event, then for each element element of that type, the user agent must delay the load event of element's node document if element's content navigable is non-null and any of the following are true:

element's content navigable's active document is not ready for post-load tasks;
element's content navigable's is delaying load events is true; or
anything is delaying the load event of element's content navigable's active document.

If, during the handling of the load event, element's content navigable is again navigated, that will further delay the load event.

Each iframe element has an associated current navigation was lazy loaded boolean, initially false. It is set and unset in the process the iframe attributes algorithm.

An iframe element whose current navigation was lazy loaded boolean is false potentially delays the load event.

Each iframe element has an associated null or DOMHighResTimeStamp pending resource-timing start time, initially set to null.

If, when the element is created, the srcdoc attribute is not set, and the src attribute is either also not set or set but its value cannot be parsed, the element's content navigable will remain at the initial about:blank Document.

If the user navigates away from this page, the iframe's content navigable's active WindowProxy object will proxy new Window objects for new Document objects, but the src attribute will not change.

The name attribute, if present, must be a valid navigable target name. The given value is used to name the element's content navigable if present when that is created.

Element/iframe#attr-sandbox

Support in all current engines.

Firefox17+Safari5+Chrome4+

Opera?Edge79+

Edge (Legacy)12+Internet Explorer10+

Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?

The sandbox attribute, when specified, enables a set of extra restrictions on any content hosted by the iframe. Its value must be an unordered set of unique space-separated tokens that are ASCII case-insensitive. The allowed values are:

When the attribute is set, the content is treated as being from a unique opaque origin, forms, scripts, and various potentially annoying APIs are disabled, and links are prevented from targeting other navigables. The allow-same-origin keyword causes the content to be treated as being from its real origin instead of forcing it into an opaque origin; the allow-top-navigation keyword allows the content to navigate its traversable navigable; the allow-top-navigation-by-user-activation keyword behaves similarly but allows such navigation only when the browsing context's active window has transient activation; the allow-top-navigation-to-custom-protocols reenables navigations toward non fetch scheme to be handed off to external software; and the allow-forms, allow-modals, allow-orientation-lock, allow-pointer-lock, allow-popups, allow-presentation, allow-scripts, and allow-popups-to-escape-sandbox keywords re-enable forms, modal dialogs, screen orientation lock, the pointer lock API, popups, the presentation API, scripts, and the creation of unsandboxed auxiliary browsing contexts respectively. The allow-downloads keyword allows content to perform downloads. [POINTERLOCK] [SCREENORIENTATION] [PRESENTATION]

The allow-top-navigation and allow-top-navigation-by-user-activation keywords must not both be specified, as doing so is redundant; only allow-top-navigation will have an effect in such non-conformant markup.

Similarly, the allow-top-navigation-to-custom-protocols keyword must not be specified if either allow-top-navigation or allow-popups are specified, as doing so is redundant.

To allow alert(), confirm(), and prompt() inside sandboxed content, both the allow-modals and allow-same-origin keywords need to be specified, and the loaded URL needs to be same origin with the top-level origin. Without the allow-same-origin keyword, the content is always treated as cross-origin, and cross-origin content cannot show simple dialogs.

Setting both the allow-scripts and allow-same-origin keywords together when the embedded page has the same origin as the page containing the iframe allows the embedded page to simply remove the sandbox attribute and then reload itself, effectively breaking out of the sandbox altogether.

These flags only take effect when the content navigable of the iframe element is navigated. Removing them, or removing the entire sandbox attribute, has no effect on an already-loaded page.

Potentially hostile files should not be served from the same server as the file containing the iframe element. Sandboxing hostile content is of minimal help if an attacker can convince the user to just visit the hostile content directly, rather than in the iframe. To limit the damage that can be caused by hostile HTML content, it should be served from a separate dedicated domain. Using a different domain ensures that scripts in the files are unable to attack the site, even if the user is tricked into visiting those pages directly, without the protection of the sandbox attribute.

When an iframe element's sandbox attribute is set or changed while it has a non-null content navigable, the user agent must parse the sandboxing directive given the attribute's value and the iframe element's iframe sandboxing flag set.

When an iframe element's sandbox attribute is removed while it has a non-null content navigable, the user agent must empty the iframe element's iframe sandboxing flag set.

In this example, some completely-unknown, potentially hostile, user-provided HTML content is embedded in a page. Because it is served from a separate domain, it is affected by all the normal cross-site restrictions. In addition, the embedded page has scripting disabled, plugins disabled, forms disabled, and it cannot navigate any frames or windows other than itself (or any frames or windows it itself embeds).

<p>We're not scared of you! Here is your content, unedited:</p>
<iframe sandbox src="https://usercontent.example.net/getusercontent.cgi?id=12193"></iframe>

It is important to use a separate domain so that if the attacker convinces the user to visit that page directly, the page doesn't run in the context of the site's origin, which would make the user vulnerable to any attack found in the page.

In this example, a gadget from another site is embedded. The gadget has scripting and forms enabled, and the origin sandbox restrictions are lifted, allowing the gadget to communicate with its originating server. The sandbox is still useful, however, as it disables plugins and popups, thus reducing the risk of the user being exposed to malware and other annoyances.

<iframe sandbox="allow-same-origin allow-forms allow-scripts"
        src="https://maps.example.com/embedded.html"></iframe>

Suppose a file A contained the following fragment:

<iframe sandbox="allow-same-origin allow-forms" src=B></iframe>

Suppose that file B contained an iframe also:

<iframe sandbox="allow-scripts" src=C></iframe>

Further, suppose that file C contained a link:

<a href=D>Link</a>

For this example, suppose all the files were served as text/html.

Page C in this scenario has all the sandboxing flags set. Scripts are disabled, because the iframe in A has scripts disabled, and this overrides the allow-scripts keyword set on the iframe in B. Forms are also disabled, because the inner iframe (in B) does not have the allow-forms keyword set.

Suppose now that a script in A removes all the sandbox attributes in A and B. This would change nothing immediately. If the user clicked the link in C, loading page D into the iframe in B, page D would now act as if the iframe in B had the allow-same-origin and allow-forms keywords set, because that was the state of the content navigable in the iframe in A when page B was loaded.

Generally speaking, dynamically removing or changing the sandbox attribute is ill-advised, because it can make it quite hard to reason about what will be allowed and what will not.

The allow attribute, when specified, determines the container policy that will be used when the permissions policy for a Document in the iframe's content navigable is initialized. Its value must be a serialized permissions policy. [PERMISSIONSPOLICY]

In this example, an iframe is used to embed a map from an online navigation service. The allow attribute is used to enable the Geolocation API within the nested context.

<iframe src="https://maps.example.com/" allow="geolocation"></iframe>

The allowfullscreen attribute is a boolean attribute. When specified, it indicates that Document objects in the iframe element's content navigable will be initialized with a permissions policy which allows the "fullscreen" feature to be used from any origin. This is enforced by the process permissions policy attributes algorithm. [PERMISSIONSPOLICY]

Here, an iframe is used to embed a player from a video site. The allowfullscreen attribute is needed to enable the player to show its video fullscreen.

<article>
 <header>
  <p><img src="/usericons/1627591962735"> <b>Fred Flintstone</b></p>
  <p><a href="/posts/3095182851" rel=bookmark>12:44</a> — <a href="#acl-3095182851">Private Post</a></p>
 </header>
 <p>Check out my new ride!</p>
 <iframe src="https://video.example.com/embed?id=92469812" allowfullscreen></iframe>
</article>

Neither allow nor allowfullscreen can grant access to a feature in an iframe element's content navigable if the element's node document is not already allowed to use that feature.

To determine whether a Document object document is allowed to use the policy-controlled-feature feature, run these steps:

If document's browsing context is null, then return false.
If document is not fully active, then return false.
If the result of running is feature enabled in document for origin on feature, document, and document's origin is "Enabled", then return true.
Return false.

Because they only influence the permissions policy of the content navigable's active document, the allow and allowfullscreen attributes only take effect when the content navigable of the iframe is navigated. Adding or removing them has no effect on an already-loaded document.

The iframe element supports dimension attributes for cases where the embedded content has specific dimensions (e.g. ad units have well-defined dimensions).

An iframe element never has fallback content, as it will always create a new child navigable, regardless of whether the specified initial contents are successfully used.

The referrerpolicy attribute is a referrer policy attribute. Its purpose is to set the referrer policy used when processing the iframe attributes. [REFERRERPOLICY]

The loading attribute is a lazy loading attribute. Its purpose is to indicate the policy for loading iframe elements that are outside the viewport.

When the loading attribute's state is changed to the Eager state, the user agent must run these steps:

Let resumptionSteps be the iframe element's lazy load resumption steps.
If resumptionSteps is null, then return.
Set the iframe's lazy load resumption steps to null.
Invoke resumptionSteps.

Descendants of iframe elements represent nothing. (In legacy user agents that do not support iframe elements, the contents would be parsed as markup that could act as fallback content.)

The HTML parser treats markup inside iframe elements as text.

HTMLIFrameElement/srcdoc

Support in all current engines.

Firefox25+Safari6+Chrome20+

Opera?Edge79+

Edge (Legacy)?Internet ExplorerNo

Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?

The srcdoc getter steps are:

Let attribute be the result of running get an attribute by namespace and local name given null, srcdoc's local name, and this.
If attribute is null, then return the empty string.
Return attribute's value.

The srcdoc setter steps are:

Let compliantString be the result of invoking the get trusted type compliant string algorithm with TrustedHTML, this's relevant global object, the given value, "HTMLIFrameElement srcdoc", and "script".

4.8.5 The iframe element

4.8.5 The `iframe` element