Iframe

References

• <iframe>: The Inline Frame Element

Related

• browsing context
• • A browsing context is an environment in which a browser displays a Document. In modern browsers, it usually is a tab, but it can be a window, a popup, a web application, or even part of a page such as a frame or an iframe.
  • Each browsing context has an origin (that of the active document) and an ordered history of previously displayed documents. Communication and resource sharing between browsing contexts is constrained, in particular between cross-origin contexts. For example, a BroadcastChannel can only be opened and used to communicate between same origin-contexts.
  • A browsing context may be part of a browsing context group, which is a set of browsing contexts that share common context like history, cookies, storage mechanisms and so on. The browsing contexts within a group can retain references to each other and can therefore inspect each other's global objects and post each other messages.
• document
• • The Document interface represents any web page loaded in the browser and serves as an entry point into the web page's context, which is the DOM tree.
• session history
• • The session history is the pages visited in the tab or frame that the current page is loaded in.
• Payment Request API
• • The Payment Request API provides a consistent user experience for merchants and users. It is not a new way of paying for things; instead, it's a way for users to select their preferred way of paying for things and make that information available to a merchant.
• Topics API
• • The Topics API provides a mechanism for developers to implement use cases such as interest-based advertising (IBA) based on topics collected by the browser as the user navigates different pages, rather than collected by the developer by tracking the user's journey around different sites with third-party cookies.
• contentWindow Property
• • The contentWindow property returns the Window object of an HTMLIframeElement. Access to the Window returned by contentWindow is subject to the rules defined by the same-origin policy, meaning that if the iframe is same-origin with the parent, then the parent can access the iframe's document and its internal DOM, and if they are cross origin, it gets very limited access to the window's attributes. See Cross-origin script API access for details.
• same-origin policy

The same-origin policy is a critical security mechanism that restricts how a document or script loaded by one origin can interact with a resource from another origin.

Notes

The <iframe> HTML element represents a nested browsing context, embedding another HTML page into the current one.

Each embedded browsing context has its own document and allows URL navigations. The navigations of each embedded browsing context are linearized into the session history of the topmost browsing context. The browsing context that embeds the others is called the parent browsing context. The topmost browsing context - the one with no parent - is usually the browser window, represented by the Window object.

Because each browsing context is a complete document environment, every <iframe> in a page requires increased memory and other computing resources. While theoretically you can use as many as you like, you should check for performance problems.

Attributes

• allow
• • Specifies a Permissions Policy for the <iframe>. This policy defines what features are available to the <iframe> (for example, access to the microphone, camera, battery, etc.) based on the origin of the request.
• allowfullscreen
• • Set to true if the iframe can activate Fullscreen mode by calling the requestFullscreen() method.
• allowpaymentrequest
• • Set to true if a cross-origin <iframe> should be allowed to invoke the Payment Request API.
• browsingtopics
• • A boolean attribute that, if present, specifies that the selected topics for the current user should be sent with the request for the <iframe>'s source.
• credentialless
• • Set to true to make the <iframe> credentialless, meaning that its content will be loaded in a new, ephemeral context. It doesn't have access to the network, cookies, and storage data associated with its origin. It uses a new context local
• csp
• • A Content-Security-Policy enforced for the embedded resource.
• height
• • The height of the frame in CSS pixels. Default is 150
• loading
• • Indicates when the browser should load the frame:
  • • eager
    • • Load the iframe immediately on page load
    • lazy
    • • Defer loading of the iframe until it reaches a calculated distance from the visual viewport, as defined by the browser. The intent is to avoid using the network and storage bandwidth required to fetch the frame until the browser is reasonably certain that it will be needed. This improves the performance and cost in most typical use cases, in particular by reducing initial page load times.
• name
• • A targetable name for the embedded browsing context. This can be used in the target attribute of the <a>, <form>, or <base> elements; the formtarget attribute of the <input> or <button> elements; or the windowName parameter of the Window.open() method.
• referrerpolicy
• • Indicated which referrer to send when fetching the frame's resource:
• sandbox
• • Controls the restrictions applied to the content embedded in the <iframe>. The value of the attribute can either be empty to apply all restrictions, or space-separated tokens to lift particular restrictions:
  • • allow-downloads
    • • Allow downloading files through an <a> or <area> element with the download attribute, as well as through the navigation that leads to the download of a file. This works regardless of whether the user clicked on the link, or JS code initiated it without user interaction.
    • allow-forms
    • • Allows the page to submit forms.
    • allow-modals
    • • Allows the page to open modal windows by Window.alert(), Window.confirm(), Window.print(), and Window.prompt(), while opening a <dialog> is allowed regardless of this keyword.
    • allow-orientation-lock
    • • Lets the resource lock the screen orientation.
    • allow-pointer-lock
    • • Allows the page to use the Pointer Lock API.
    • allow-popups
    • • Allows popups (like from WIndow.open(), target="_blank", Window.showModalDialog()). If this keyword is not used, that functionality will silently fail.
    • allow-popups-to-escape-sandbox
    • • Allows a sandboxed document to open a new browsing context without forcing the sandboxing flags upon it. This will allow, for example, a third-party advertisement to be safely sandboxed without forcing the same restrictions upon the page the ad links to. If this flag is not included, a redirected page, popup window, or new tab will be subject to the same sandbox restrictions as the originating <iframe>.
    • allow-presentation
    • • Allows embedders to have control over whether an iframe can start a presentation session.
    • allow-same-origin
    • • If this token is not used, the resource is treated as being from a special origin that always fails the same-origin policy (potentially preventing access to data/storage cookies and some JavaScript APIs).
    • allow-scripts
    • • Allows the page to run scripts (but not create pop-up windows). If this keyword is not used, this operation is not allowed.
    • allow-storage-access-by-user-activation
    • • Allows a document loaded in the <iframe> to use the Storage Access API to request access to unpartitioned cookies.
    • allow-top-navigation
    • • Lets the resource navigate the top-level browsing context (the one named _top).
    • allow-top-navigation-by-user-activation
    • • Lets the resource navigate the top-level browsing context, but only if initiated by a user gesture.
    • allow-top-navigation-to-custom-protocols
    • • Allows navigations to non-http protocols built into a browser or registered by a website. This feature is also activated by allow-popups or allow-top-level-navigation keyword.

Note: When the embedded document has the same origin as the embedding page, it is strongly discouraged to use both allow-scripts and allow-same-origin, as that lets the embedded document remove the sandbox attribute - making it no more secure than not using the sandbox attribute at all.

Note: When redirecting the user, opening a popup window, or opening a new tab from an embedded page within an <iframe> with the sandbox attribute, the new browsing context is subject to the same sandbox restrictions. This can create issues - for example, if a page embedded within a <iframe> without a sandbox="allow-forms" or sandbox="allow-popups-to-escape-sandbox" attribute set on it opens a new site in a separate tab, form submission in that new browsing content will silently fail.

• src
• • The URL of the page to embed. Use a value of about:blank to embed an empty page that conforms to the same-origin policy. Also note that programmatically removing an <iframe>'s src attribute cases about:blank to be loaded in the frame in many browsers.
• srcdoc
• • Inline HTML to embed. overriding the src attribute. Its content should follow the syntax of a full HTML document, which includes the doctype directive, <html>, <body> tags, etc.
• width
• • The width of the frame in CSS pixels. The default is 500

The <iframe> in which Google Colab shows output:

  <iframe allow="accelerometer; autoplay; gyroscope; magnetometer; xr-spatial-tracking; clipboard-write" sandbox="allow-downloads allow-forms allow-pointer-lock allow-popups allow-popups-to-escape-sandbox allow-same-origin allow-scripts allow-storage-access-by-user-activation allow-modals" src="https://2rls97j4t4g-496ff2e9c6d22116-0-colab.googleusercontent.com/outputframe.html?vrz=colab_20250124-060219_RC00_719217321" class="" style="height: 506px;"></iframe>

Scripting

Inline frames, like <frame> elements, are included in the window.frames pseudo-array. With the DOM HTMLIframe object, scripts can access the window object of the framed resource via the contentWindow property. The contentDocument property refers to the document inside the <iframe>, same as contentWindow.document.

From the inside of a frame, a script can get a reference to its parent window with window.parent. Script access to a frame's content is subject to the same-origin policy. Scripts access to a frame's content is subject to the same-origin policy. Scripts cannot access most properties in other window objects if the script was loaded from a different origin, including scripts inside a frame accessing the frame's parent. Cross-origin communication can be achieved using Window.postMessage().

Position and Scaling

Being a replaced element, the <iframe> allows the position of the embedded document within its box to be adjusted using the object-position property.

error and load event behavior

The error and load events fired on <iframe>s could be used to probe the URL space of the local network's HTTP servers. Therefore, as a security precaution user agents do not fire the error event on <iframe>s, and the load event is always triggered even when if the <iframe> content fails to load.