iframe element

If you don't know what an element is or how you must use it, I recommend you read the "HTML tags and attributes" tutorial that you can find in the HTML tutorials section.

Description

The iframe element represents a nested browsing context, which is basically a document nested in the current document. The address from where the browser should retrieve the embedded document can be provided in the src attribute and lately, since the introduction of HTML5, this document can also be fully included as content of the srcdoc attribute.

The sandbox attribute, new in HTML5, fences the content of the embedded document disabling potentially harmful or annoying features like forms and scripts. This allows authors to safely embed third party content.

The iframe element is an empty element, which means it can't have content between its opening and closing tags.

Examples

This example shows a basic and traditional use of the iframe element. Here we're embedding a document, prepared specifically for this example, by specifying its URI in the src attribute. You'll see how the browser applies a default height and conveniently provides the scrollbars to access the content that's outside the viewport. Additionally, we're using CSS to make the element take all the horizontal space available, in order to improve presentation. If no style is applied, the element would have a default and fixed width.

In this example we're emulating a very common and useful practice, where authors include live versions of external documents for reference purposes. This implementation could be easily adapted to fit another very frequent use of the element, which consist in pieces of content dynamically loaded into the iframe upon user interaction. This technique requires client-side scripting.

<h1>Cracking nuts like a master</h1>
<p>There's never been a nut cracker that didn't go by the book, so the first step you need to take is to read the "Nut cracker specification". For your convenience, we've added a live version of the specification in this document. Enjoy!</p>
<iframe src="iframe-example-1.html" style="width: 100%"></iframe>

Cracking nuts like a master

There's never been a nut cracker that didn't go by the book, so the first step you need to take is to read the "Nut cracker specification". For your convenience, we've added a live version of the specification in this document. Enjoy!

The second example shows the comments section for a pulbication, where users discuss about the subject treated in the article. The author of this document has conveniently added the comments as content of the srcdoc attribute of an iframe, to provide an extra layer of security, thanks to the sandbox attribute. The mere presence of this attribute will prevent the execution of potentially harmful or annoying features, protecting the document from script injections made by unwanted participants.

Note that all double quotes (") and ampersand symbols (&) must be escaped (with &quot; and &amp; respectively) inside the srcdoc attribute to prevent browsers from incorrectly parsing its content.

<h2>Comments</h2>
<p>Demain said:</p>
<iframe style="border: 0; margin: 0" srcdoc="<p>The fact is that you can never be &quot;sure&quot; about it...</p>" sandbox></iframe>
<p>Jhonny said:</p>
<iframe style="border: 0; margin: 0" srcdoc="<p>If you keep that attitude I'll inject a virus in your article!</p><p>I warn you, I'm a seasoned hacker!</p>" sandbox></iframe>

Comments

Demain said:

Jhonny said:

Note: the previous example contains some CSS declarations to to improve presentation.

Attributes

Specific attributes

src

The URI of the embedded document.

The srcdoc attribute, if present, takes precedence over src. In case the browser doesn't support the recently introduced srcdoc attribute, src acts as a fallback.

This attribute is mandatory if the itemprop attribute is present, as it's used to determine the value of the property.

Example

<iframe src="http://www.otrositio.com/articulos/acerca-de-la-verdad.html"></iframe>

srcdoc

A document that will be rendered inside this element.

The srcdoc attribute, if present, takes precedence over src. In case the browser doesn't support the recently introduced srcdoc attribute, src acts as a fallback.

As of 2015-05-01, browser support for this attribute is incomplete. Authors may have to use the src as fallback until support grows.

Example

<iframe style="border: 0; margin: 0" srcdoc="<h1>A handful of opportunities</h1><p>I know you're looking for some new adventure again...</p>"></iframe>

name

A name for the nested browsing context the element defines. The name provided in this attribute can be used in other elements (like a, area or form) to specify the target browsing context where the element's action will be executed.

This attribute has been deprecated in previous versions of HTML in favor of the id attribute. HTML5 has reinstated it in order to provide a name for nested browsing contexts, a different approach from the one adopted by id.

Example

<iframe src="http://www.othersite.com/about-me.html" name="context1"></iframe>

sandbox

A set of values indicating what restrictions should be applied to the document inside this iframe. When this attribute is present, it instructs the browser to disable certain potentially harmful or annoying features like scripts or forms.

As content, it acepts a space-separated list of strings, each of which indicate a particular feature to be allowed. Below, all possible values in this list are being described:

  • allow-forms: form submissions are allowed.
  • allow-modals: modal dialogs are allowed.
  • allow-orientation-lock: changes on the screen orientation are allowed.
  • allow-pointer-lock: the Pointer Lock API is allowed.
  • allow-popups: new windows can be opened from inside the iframe's document (for example, using the target attribute or client-side scripts).
  • allow-popups-to-escape-sandbox: auxiliary browsing contexts are allowed to escape the sandbox restriction. When this feature isn't present, any auxiliary browsing context created inside this context inherits the sandbox restrictions.
  • allow-presentation: the Presentation API, used to control presentation devices such as projectors or connected TVs, is allowed.
  • allow-same-origin: scripts are allowed to affect only the contents of the document inside this iframe.
  • allow-scripts: script execution is allowed.
  • allow-top-navigation: the navigation of the top-level browsing context (the iframe's parent) is allowed.

If the sandbox attribute is present, all previously listed features are disabled by default. To prevent a feature from being blocked, it must be present in the list of this attribute.

This attribute has been recently added to HTML5. Despite this fact, browser support is fairly complete and authors can use it, at least, to protect their documents in supporting browsers.

Example

<iframe src="http://www.acantoate.com/senza-parole.html" sandbox="allow-scripts allow-same-origin allow-forms"></iframe>
<iframe src="http://www.othersite.com/articles/genius-in-me.html" sandbox></iframe>

allowfullscreen

A boolean value indicating if the document provided by this element is allowed to go fullscreen, which means covering the entire area of the screen. When this attribute has the value "allowfullscreen" or the empty string (""), or when it's just present, the fullscreen mode is allowed for the document provided by this element.

This attribute has been introduced to the standard in HTML5, and support provided by browsers is partial (as of 2014-10-07). Authors should avoid relying on this feature to deliver important content.

Example

<iframe src="http://www.the-world-of-articles.com/a-broad-view.html" allowfullscreen></iframe>

allowpaymentrequest

A boolean value indicating if the document provided by this element is allowed to use the Payment request API to request payments. When this attribute has the value "allowpaymentrequest" or the empty string (""), or when it's just present, the document will have access to payment requests.

This attribute has been introduced to the standard in HTML5, and support provided by browsers is partial (as of 2014-10-07). Authors should avoid relying on this feature to deliver important content.

Example

<iframe src="http://www.shopping-shopping.com/art-315436843.html" allowpaymentrequest></iframe>

allowusermedia

A boolean value indicating if the document provided by this element is allowed to access the web cam or other video or audio input. When this attribute has the value "allowusermedia" or the empty string (""), or when it's just present, the document contained by this element can acces input devices.

This attribute has been recently introduced to HTML5, and support provided by browsers is expected to be poor. Authors should avoid relying on this feature to deliver important content.

Example

<iframe src="http://www.a-new-era.com/the-hacker.html" allowusermedia></iframe>

width

A number of pixels indicating the width of the element. If this attribute is omitted a default value will be used.

Example

<iframe src="http://www.misunderstood-because.com/out-of-my-mind.html" width="600"></iframe>

height

A number of pixels indicating the height of the element. If this attribute is omitted a default value will be used.

Example

<iframe src="http://www.misunderstood-because.com/going-mad.html" height="250"></iframe>

referrerpolicy

Sets the referrer policy used when processing the element's attributes, which involves what information is sent about the referrer in a request to another resource. It may contain any of the following values:

  • no-referrer: No information about the referrer is sent in all requests.
  • no-referrer-when-downgrade: A full URL is sent only in requests from a TLS-protected enviroment (HTTPS) to a potentially thrusworthy URL and from a not TLS-protected enviroment to anywhere.
  • same-origin: A full URL is sent only in requests made in the same origin.
  • origin: A URL composed by protocol, host and port is sent in all requests.
  • strict-origin: A URL composed by protocol, host and port is sent only in requests from a TLS-protected enviroment (HTTPS) to a potentially thrusworthy URL and from a not TLS-protected enviroment to anywhere.
  • origin-when-cross-origin: A full URL is sent in requests made in the same origin and a URL composed by protocol, host and port is sent in cross-origin requests.
  • strict-origin-when-cross-origin: A full URL is sent in requests made in the same origin and a URL composed by protocol, host and port is sent in cross-origin requests, only in requests from a TLS-protected enviroment (HTTPS) to a potentially thrusworthy URL and from a not TLS-protected enviroment to anywhere.
  • unsafe-url: A full URL is sent in all request.

Note: When this attribute takes the empty string, the value no-referrer is assumed.

Example

<iframe src="http://www.spying-the-world.com/the-thing-with-cia.html" referrerpolicy="no-referrer"></iframe>

seamless

A boolean value indicating if the styles of the parent document should be applied to the document inside this iframe. If the attribute has the value "seamless" or the empty string (""), or if it's just present, the styles of the main document are shared with the document in this iframe.

This attribute has become recently obsolete in HTML5 due to little implementation by both, authors and browsers. Its use is no longer valid.

Example

<iframe src="http://www.butterflies-and-unicorns.com/shiny-in-the-wind.html"></iframe>

longdesc

The URI of a resource with a detailed explanation of the element's content/purpose.

This attribute has become obsolete in HTML5 due to little implementation by both, authors and browsers. Its functionality can be replaced with aria attributes.

Example

<iframe src="http://www.url001.com/tresure-map.html" longdesc="tresure-map-explanation.html"></iframe>

align

The horizontal alignment of the element with respect to its surroundings. There are four possible values (case-insensitive):

  • left: element is aligned to the left margin.
  • center: element is centered.
  • right: element is aligned to the right margin.
  • justify: element is justified or aligned to both margins.

This attribute has become obsolete in HTML5 and, therefore, its use is no longer valid. Authors should replace it with style sheets declarations.

Example

<iframe src="http://www.a-new-website.com" align="center"></iframe>

frameborder

A boolean value indicating if a border should be drawn around the element. If the attribute has the value "1", a border will be drawn. If it has the value "0" it will have no border.

This attribute has beecome obsolete in HTML5 because of its presentational nature. Authors are adviced to use style sheets declarations instead.

Example

<iframe src="http://www.another-new-website.com" frameborder="0"></iframe>

marginheight

A number of pixels to use as top and bottom margin for the element.

This attribute has been removed in HTML5 and its use is no longer valid. Authors are adviced to use style sheets declarations instead.

Example

<iframe src="../shining-star.html" marginheight="20"></iframe>

marginwidth

A number of pixels to use as left and right margin for the element.

This attribute has become obsolete in HTML5 because of its presentational nature. Authors are adviced to use style sheets declarations instead.

Example

<iframe src="../shining-star.html" marginwidth="50"></iframe>

scrolling

A string indicating how scrollbars should be provided for this element. The three case-insensitive values it can take are:

  • auto: scrolling devices are provided only when necessary.
  • yes: scrolling devices are always provided.
  • no: scrolling devices are never provided.

Example

This attribute has been removed in HTML5 and its use is no longer valid. Authors are adviced to use style sheets declarations instead.

<iframe src="../shining-star.html" scrolling="no"></iframe>

Global attributes

For information about global attributes refer to this list of global attributes in HTML5.

Events

Global events

For information about global events refer to this list of global events in HTML5.