4.8.2 The iframe element

The srcdoc attribute gives the content of the page that the nested browsing context is to contain. The value of the attribute is the source of an iframe srcdoc document.

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

For iframe elements in XML documents, the srcdoc attribute, if present, must have a value that matches the production labeled document in the XML specification. [XML]

Here a blog uses the srcdoc attribute in conjunction with the sandbox and seamless attributes 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 seamless 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 seamless 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 seamless 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.

In the HTML syntax, authors need only remember to use """ (U+0022) characters to wrap the attribute contents and then to escape all """ (U+0022) and U+0026 AMPERSAND (&) characters, and to specify the sandbox attribute, to ensure safe embedding of content.

Due to restrictions of the XHTML syntax, 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 "tab" (U+0009), "LF" (U+000A), and "CR" (U+000D) — 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.

When an iframe element is inserted into a document, the user agent must create a nested browsing context, and then process the iframe attributes for the first time.

When an iframe element is removed from a document, the user agent must discard the nested browsing context.

This happens without any unload events firing (the nested browsing context and its Document are discarded, not unloaded).

Whenever an iframe element with a nested browsing context has its srcdoc attribute set, changed, or removed, the user agent must process the iframe attributes.

Similarly, whenever an iframe element with a nested browsing context but with no srcdoc attribute specified has its src attribute set, changed, or removed, the user agent must process the iframe attributes.

When the user agent is to process the iframe attributes, it must run the first appropriate steps from the following list:

If the srcdoc attribute is specified

Navigate the element's child browsing context to a resource whose Content-Type is text/html, whose URL is about:srcdoc, and whose data consists of the value of the attribute. The resulting Document must be considered an iframe srcdoc document.

Otherwise, if the element has no src attribute specified, and the user agent is processing the iframe's attributes for the first time

Queue a task to fire a simple event named load at the iframe element.

Otherwise

If the value of the src attribute is the empty string, let url be the string "about:blank".

Otherwise, resolve the value of the src attribute, relative to the iframe element.

If that is not successful, then let url be the string "about:blank". Otherwise, let url be the resulting absolute URL.
Navigate the element's child browsing context to url.

Any navigation required of the user agent in the process the iframe attributes algorithm must be completed as an explicit self-navigation override and with the iframe element's document's browsing context as the source browsing context.

Furthermore, if the active document of the element's child browsing context before such a navigation was not completely loaded at the time of the new navigation, then the navigation must be completed with replacement enabled.

Similarly, if the child browsing context's session history contained only one Document when the process the iframe attributes algorithm was invoked, and that was the about:blank Document created when the child browsing context was created, then any navigation required of the user agent in that algorithm must be completed with replacement enabled.

When a Document in an iframe is marked as completely loaded, the user agent must synchronously fire a simple event named load at the iframe element. When content whose URL has the same origin as the iframe element's Document fails to load (e.g. due to a DNS error, network error, or if the server returned a 4xx or 5xx status code or equivalent), then the user agent must queue a task to fire a simple event named error at the element instead. (This event does not fire for parse errors, script errors, or any errors for cross-origin resources.)

The task source for these tasks is the DOM manipulation task source.

A load event is also fired at the iframe element when it is created if no other data is loaded in it.

When the iframe's active document is not ready for post-load tasks, and when anything in the iframe is delaying the load event of the iframe's browsing context's active document, the iframe must delay the load event of its document.

If, during the handling of the load event, the browsing context in the iframe is again navigated, that will further delay the load event.

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 resolved, the browsing context will remain at the initial about:blank page.

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

Whenever the name attribute is set, the nested browsing context's name must be changed to the new value. If the attribute is removed, the browsing context name must be set to the empty string.

When the attribute is set, the content is treated as being from a unique origin, forms and scripts are disabled, links are prevented from targeting other browsing contexts, and plugins are secured. The allow-same-origin keyword allows the content to be treated as being from the same origin instead of forcing it into a unique origin, the allow-top-navigation keyword allows the content to navigate its top-level browsing context, and the allow-forms, allow-popups and allow-scripts keywords re-enable forms, popups, and scripts respectively.

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 nested browsing context of the iframe 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 with a sandbox attribute has its nested browsing context created (before the initial about:blank Document is created), and when an iframe element's sandbox attribute is set or changed while it has a nested browsing context, the user agent must parse the sandboxing directive using the attribute's value as the input and the iframe element's nested browsing context's iframe sandboxing flag set as the output.

When an iframe element's sandbox attribute is removed while it has a nested browsing context, the user agent must empty the iframe element's nested browsing context's iframe sandboxing flag set as the output.

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 nested browsing context 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 seamless attribute is a boolean attribute. When specified, it indicates that the iframe element's browsing context is to be rendered in a manner that makes it appear to be part of the containing document (seamlessly included in the parent document).

An iframe element is said to be in seamless mode when all of the following conditions are met:

The seamless attribute is set on the iframe element, and
The iframe element's owner Document's active sandboxing flag set does not have the sandboxed seamless iframes flag set, and
Either:
- The browsing context's active document has the same origin as the iframe element's Document, or
- The browsing context's active document's address has the same origin as the iframe element's Document, or
- The browsing context's active document is an iframe srcdoc document.

When an iframe element is in seamless mode, the following requirements apply:

The user agent must set the seamless browsing context flag to true for that browsing context. This will cause links to open in the parent browsing context unless an explicit self-navigation override is used (target="_self").
Media queries in the context of the iframe's browsing context (e.g. on media attributes of style elements in Documents in that iframe) must be evaluated with respect to the nearest ancestor browsing context that is not itself being nested through an iframe that is in seamless mode. [MQ]
In a CSS-supporting user agent: the user agent must add all the style sheets that apply to the iframe element to the cascade of the active document of the iframe element's nested browsing context, at the appropriate cascade levels, before any style sheets specified by the document itself.
In a CSS-supporting user agent: the user agent must, for the purpose of CSS property inheritance only, treat the root element of the active document of the iframe element's nested browsing context as being a child of the iframe element. (Thus inherited properties on the root element of the document in the iframe will inherit the computed values of those properties on the iframe element instead of taking their initial values.)
In visual media, in a CSS-supporting user agent: the user agent should set the intrinsic width of the iframe to the width that the element would have if it was a non-replaced block-level element with 'width: auto', unless that width would be zero (e.g. if the element is floating or absolutely positioned), in which case the user agent should set the intrinsic width of the iframe to the shrink-to-fit width of the root element (if any) of the content rendered in the iframe.
In visual media, in a CSS-supporting user agent: the user agent should set the intrinsic height of the iframe to the shortest height that would make the content rendered in the iframe at its current width (as given in the previous bullet point) have no scrollable overflow at its bottom edge. Scrollable overflow is any overflow that would increase the range to which a scrollbar or other scrolling mechanism can scroll.
In visual media, in a CSS-supporting user agent: the user agent must force the height of the initial containing block of the active document of the nested browsing context of the iframe to zero.

This is intended to get around the otherwise circular dependency of percentage dimensions that depend on the height of the containing block, thus affecting the height of the document's bounding box, thus affecting the height of the viewport, thus affecting the size of the initial containing block.
In speech media, the user agent should render the nested browsing context without announcing that it is a separate document.
User agents should, in general, act as if the active document of the iframe's nested browsing context was part of the document that the iframe is in, if any.

For example if the user agent supports listing all the links in a document, links in "seamlessly" nested documents would be included in that list without being significantly distinguished from links in the document itself.

If the attribute is not specified, or if the origin conditions listed above are not met, then the user agent should render the nested browsing context in a manner that is clearly distinguishable as a separate browsing context, and the seamless browsing context flag must be set to false for that browsing context.

It is important that user agents recheck the above conditions whenever the active document of the nested browsing context of the iframe changes, such that the seamless browsing context flag gets unset if the nested browsing context is navigated to another origin.

The attribute can be set or removed dynamically, with the rendering updating in tandem.

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 nested browsing context, regardless of whether the specified initial contents are successfully used.

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.)

When used in HTML documents, the allowed content model of iframe elements is text, except that invoking the HTML fragment parsing algorithm with the iframe element as the context element and the text contents as the input must result in a list of nodes that are all phrasing content, with no parse errors having occurred, with no script elements being anywhere in the list or as descendants of elements in the list, and with all the elements in the list (including their descendants) being themselves conforming.

HTML5

A vocabulary and associated APIs for HTML and XHTML

W3C Working Draft 25 October 2012

4.8.2 The `iframe` element