HTML: The Living Standard

Edition for Web Developers — Last Updated 21 November 2024

1. 1. 1. 4.8.5 The iframe element
      2. 4.8.6 The embed element
      3. 4.8.7 The object element

4.8.5 The iframe element

Categories:

Flow content.

Phrasing content.

Embedded content.

Interactive content.

Palpable content.

Contexts in which this element can be used:

Where embedded content is expected.

Content model:

Nothing.

Tag omission in text/html:

Neither tag is omissible.

Content attributes:

Global attributes

src — Address of the resource

srcdoc — A document to render in the iframe

name — Name of content navigable

sandbox — Security rules for nested content

allow — Permissions policy to be applied to the iframe's contents

allowfullscreen — Whether to allow the iframe's contents to use requestFullscreen()

width — Horizontal dimension

height — Vertical dimension

referrerpolicy — Referrer policy for fetches initiated by the element

loading — Used when determining loading deferral

Accessibility considerations:

For authors.

For implementers.

DOM interface:

Uses HTMLIFrameElement.

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.

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:

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

The above requirements apply in XML documents as well.

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

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

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.

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.

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:

• allow-downloads
• allow-forms
• allow-modals
• allow-orientation-lock
• allow-pointer-lock
• allow-popups
• allow-popups-to-escape-sandbox
• allow-presentation
• allow-same-origin
• allow-scripts
• allow-top-navigation
• allow-top-navigation-by-user-activation
• allow-top-navigation-to-custom-protocols

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.

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

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

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

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

<a href=D>Link</a>

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]

<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]

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

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:

1. Let resumptionSteps be the iframe element's lazy load resumption steps.

2. If resumptionSteps is null, then return.

3. Set the iframe's lazy load resumption steps to null.

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

<iframe src="https://ads.example.com/?customerid=923513721&amp;format=banner"
        width="468" height="60"></iframe>

4.8.6 The embed element

Categories:

Flow content.

Phrasing content.

Embedded content.

Interactive content.

Palpable content.

Contexts in which this element can be used:

Where embedded content is expected.

Content model:

Nothing.

Tag omission in text/html:

No end tag.

Content attributes:

Global attributes

src — Address of the resource

type — Type of embedded resource

width — Horizontal dimension

height — Vertical dimension

Any other attribute that has no namespace (see prose).

Accessibility considerations:

For authors.

For implementers.

DOM interface:

The embed element provides an integration point for an external application or interactive content.

The src attribute gives the URL of the resource being embedded. The attribute, if present, must contain a valid non-empty URL potentially surrounded by spaces.

If the itemprop attribute is specified on an embed element, then the src attribute must also be specified.

The type attribute, if present, gives the MIME type by which the plugin to instantiate is selected. The value must be a valid MIME type string. If both the type attribute and the src attribute are present, then the type attribute must specify the same type as the explicit Content-Type metadata of the resource given by the src attribute.

The embed element supports dimension attributes.

4.8.7 The object element

Categories:

Flow content.

Phrasing content.

Embedded content.

Listed form-associated element.

Palpable content.

Contexts in which this element can be used:

Where embedded content is expected.

Content model:

Transparent.

Tag omission in text/html:

Neither tag is omissible.

Content attributes:

Global attributes

data — Address of the resource

type — Type of embedded resource

name — Name of content navigable

form — Associates the element with a form element

width — Horizontal dimension

height — Vertical dimension

Accessibility considerations:

For authors.

For implementers.

DOM interface:

Uses HTMLObjectElement.

The object element can represent an external resource, which, depending on the type of the resource, will either be treated as an image or as a child navigable.

The data attribute specifies the URL of the resource. It must be present, and must contain a valid non-empty URL potentially surrounded by spaces.

The type attribute, if present, specifies the type of the resource. If present, the attribute must be a valid MIME type string.

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 applicable, and if present when the element's content navigable is created.

The form attribute is used to explicitly associate the object element with its form owner.

The object element supports dimension attributes.

<figure>
 <object data="clock.html"></object>
 <figcaption>My HTML Clock</figcaption>
</figure>