{{APIRef("HTML DOM")}}
The HTMLIFrameElement interface provides special properties and methods (beyond those of the {{domxref("HTMLElement")}} interface it also has available to it by inheritance) for manipulating the layout and presentation of inline frame elements.
Properties
Inherits properties from its parent, {{domxref("HTMLElement")}}.
- {{domxref("HTMLIFrameElement.align")}} {{obsolete_inline}}
- Is a {{domxref("DOMString")}} that specifies the alignment of the frame with respect to the surrounding context.
- {{domxref("HTMLIFrameElement.allowfullscreen")}} {{experimental_inline}}
- Is a {{domxref("Boolean")}} that indicates whether or not the inline frame is willing to be placed into full screen mode. See Using full-screen mode for details.
- {{domxref("HTMLIFrameElement.contentDocument")}} {{readonlyInline}}
- Returns a {{domxref("Document")}}, the active document in the inline frame's nested browsing context.
- {{domxref("HTMLIFrameElement.contentWindow")}} {{readonlyInline}}
- Returns a {{domxref("WindowProxy")}}, the window proxy for the nested browsing context.
- {{domxref("HTMLIFrameElement.frameBorder")}} {{obsolete_inline}}
- Is a {{domxref("DOMString")}} that indicates whether to create borders between frames.
- {{domxref("HTMLIFrameElement.height")}}
- Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("height", "iframe")}} HTML attribute, indicating the height of the frame.
- {{domxref("HTMLIFrameElement.longDesc")}} {{obsolete_inline}}
- Is a {{domxref("DOMString")}} that contains the URI of a long description of the frame.
- {{domxref("HTMLIFrameElement.marginHeight")}} {{obsolete_inline}}
- Is a {{domxref("DOMString")}} being the height of the frame margin.
- {{domxref("HTMLIFrameElement.marginWidth")}} {{obsolete_inline}}
- Is a {{domxref("DOMString")}} being the width of the frame margin.
- {{domxref("HTMLIFrameElement.name")}}
- Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("name", "iframe")}} HTML attribute, containing a name by which to refer to the frame.
- {{domxref("HTMLIFrameElement.referrerPolicy")}} {{experimental_inline}}
- Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("referrerPolicy", "iframe")}} HTML attribute indicating which referrer to use when fetching the linked resource.
- {{domxref("HTMLIFrameElement.sandbox")}}
- Is a {{domxref("DOMSettableTokenList")}} that reflects the {{htmlattrxref("sandbox", "iframe")}} HTML attribute, indicating extra restrictions on the behavior of the nested content.
- {{domxref("HTMLIFrameElement.scrolling")}} {{obsolete_inline}}
- Is a {{domxref("DOMString")}} that indicates whether the browser should provide scrollbars for the frame.
- {{domxref("HTMLIFrameElement.seamless")}} {{experimental_inline}}
- Is a {{domxref("Boolean")}} that reflects the {{htmlattrxref("seamless", "iframe")}} HTML attribute, indicating that the inline frame should be rendered seamlessly within the parent document.
- {{domxref("HTMLIFrameElement.src")}}
- Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("src", "iframe")}} HTML attribute, containing the address of the content to be embedded.
- {{domxref("HTMLIFrameElement.srcdoc")}}
- Is a {{domxref("DOMString")}} that represents the content to display in the frame.
- {{domxref("HTMLIFrameElement.width")}}
- Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("width", "iframe")}} HTML attribute, indicating the width of the frame.
Methods
Inherits properties from its parent, {{domxref("HTMLElement")}}.
Firefox OS Browser API methods
To support the requirement of a browser {{HTMLElement("iframe")}}, Firefox OS extends HTMLIFrameElement with new methods that give the {{HTMLElement("iframe")}} some super powers.
Navigation methods
The following navigation methods allow navigation through the browsing history of the {{HTMLElement("iframe")}}. They are necessary to be able to implement back, forward, stop, and reload buttons.
- {{domxref("HTMLIFrameElement.reload","reload()")}}
- Allows reloading of the {{HTMLElement("iframe")}} element content.
- {{domxref("HTMLIFrameElement.stop","stop()")}}
- Allows stopping of the {{HTMLElement("iframe")}}'s content loading.
- {{domxref("HTMLIFrameElement.getCanGoBack","getCanGoBack()")}}
- Indicates whether it's possible to navigate backwards.
- {{domxref("HTMLIFrameElement.goBack","goBack()")}}
- Changes the location of the {{HTMLElement("iframe")}} for the previous location in its browsing history.
- {{domxref("HTMLIFrameElement.getCanGoForward","getCanGoForward()")}}
- Indicates whether it's possible to navigate forward.
- {{domxref("HTMLIFrameElement.goForward","goForward()")}}
- Changes the location of the {{HTMLElement("iframe")}} for the next location in its browsing history.
Management methods
The next set of methods manage the resources used by a browser {{HTMLElement("iframe")}}. These are especially useful for implementing tabbed browser application.
- {{domxref("HTMLIFrameElement.executeScript","executeScript()")}}
- Allows a specified script to be executed against a page loaded in the browser {{HTMLElement("iframe")}}.
- {{domxref("HTMLIFrameElement.purgeHistory","purgeHistory()")}}
- Clears all the resources (cookies, localStorage, cache, etc.) associated with the browser {{HTMLElement("iframe")}}.
- {{domxref("HTMLIFrameElement.setVisible","setVisible()")}}
- Changes the visibility state of a browser {{HTMLElement("iframe")}}. This can influence resource allocation and some function usage such as {{domxref("window.requestAnimationFrame","requestAnimationFrame")}}.
- {{domxref("HTMLIFrameElement.getVisible","getVisible()")}}
- Indicates the current visibility state of the browser {{HTMLElement("iframe")}}.
- {{domxref("HTMLIFrameElement.setActive","setActive()")}}
- Sets the current {{HTMLElement("iframe")}} as the active frame, which has an effect on how it is prioritized by the process manager.
- {{domxref("HTMLIFrameElement.getActive","getActive()")}}
- Indicates whether the current browser {{htmlelement("iframe")}} is the currently active frame.
- {{domxref("HTMLIFrameElement.setInputMethodActive","setInputMethodActive()")}}
- Sets the current browser {{HTMLElement("iframe")}} as an active IME window and other iframes as non-active IME windows. Useful when a top level app wants to activate a window as an IME (Input Method Editor, like a keyboard.)
- {{domxref("HTMLIFrameElement.setNfcFocus", "setNfcFocus()")}} {{PlatformOnlyInline("Firefox OS", "2.2+")}}
- Part of the Firefox OS NFC API, extending the Browser API, this sets whether a browser {{htmlelement("iframe")}} can receive an NFC event.
Audio-related methods
The following methods allow direct control of sound in the browser element.
- {{domxref("HTMLIFrameElement.getVolume", "getVolume()")}} {{PlatformOnlyInline("Firefox OS", "2.5+")}}
- Gets the current volume of the browser {{HTMLElement("iframe")}}.
- {{domxref("HTMLIFrameElement.setVolume", "setVolume()")}} {{PlatformOnlyInline("Firefox OS", "2.5+")}}
- Sets the current volume of the browser {{HTMLElement("iframe")}}.
- {{domxref("HTMLIFrameElement.mute", "mute()")}} {{PlatformOnlyInline("Firefox OS", "2.5+")}}
- Mutes any audio playing in the browser {{HTMLElement("iframe")}}.
- {{domxref("HTMLIFrameElement.unmute", "unmute()")}} {{PlatformOnlyInline("Firefox OS", "2.5+")}}
- Unmutes any audio playing in the browser {{HTMLElement("iframe")}}.
- {{domxref("HTMLIFrameElement.getMuted", "getMuted()")}} {{PlatformOnlyInline("Firefox OS", "2.5+")}}
- Indicates whether the browser {{HTMLElement("iframe")}} is currently muted.
Search methods
New methods are provided to allow programmatic searches of browser {{HTMLElement("iframe")}}s to be carried out.
- {{domxref("HTMLIFrameElement.findAll","findAll()")}} {{PlatformOnlyInline("Firefox OS", "2.5+")}}
- Searches for a string in a browser {{HTMLElement("iframe")}}'s content; if found, the first instance of the string relative to the caret position will be highlighted.
- {{domxref("HTMLIFrameElement.findNext","findNext()")}} {{PlatformOnlyInline("Firefox OS", "2.5+")}}
- Highlights the next or previous instance of a search result after a {{domxref("HTMLIFrameElement.findAll","findAll()")}} search has been carried out.
- {{domxref("HTMLIFrameElement.clearMatch","clearMatch()")}} {{PlatformOnlyInline("Firefox OS", "2.5+")}}
- Clears any content highlighted by {{domxref("HTMLIFrameElement.findAll","findAll()")}} or {{domxref("HTMLIFrameElement.findNext","findNext()")}}.
Event-related methods
In order to manage the browser {{HTMLElement("iframe")}}'s content, many new events were added (see below). The following methods are used to deal with those events:
- The {{HTMLElement("iframe")}} gains support for the methods of the {{domxref("EventTarget")}} interface
- {{domxref("EventTarget.addEventListener","addEventListener()")}}, {{domxref("EventTarget.removeEventListener","removeEventListener()")}}, and {{domxref("EventTarget.dispatchEvent","dispatchEvent()")}}.
- {{domxref("HTMLIFrameElement.sendMouseEvent","sendMouseEvent()")}}
- Sends a {{domxref("MouseEvent")}} to the {{HTMLElement("iframe")}}'s content.
- {{domxref("HTMLIFrameElement.sendTouchEvent","sendTouchEvent()")}}
- Sends a {{domxref("TouchEvent")}} to the {{HTMLElement("iframe")}}'s content. Note that this method is available for touch enabled devices only.
- {{domxref("HTMLIFrameElement.addNextPaintListener","addNextPaintListener()")}}
- Defines a handler to listen for the next {{event("MozAfterPaint")}} event in the browser {{HTMLElement("iframe")}}.
- {{domxref("HTMLIFrameElement.removeNextPaintListener","removeNextPaintListener()")}}
- Removes a handler previously set with {{domxref("HTMLIFrameElement.addNextPaintListener","addNextPaintListener()")}}.
Utility methods
Last, there are some utility methods, useful for apps that host a browser {{HTMLElement("iframe")}}.
- {{domxref("HTMLIFrameElement.download","download()")}}
- Downloads a specified URL, storing it at the specified filename/path.
- {{domxref("HTMLIFrameElement.getContentDimensions","getContentDimensions()")}}
- Retrieves the X and Y dimensions of the content window.
- {{domxref("HTMLIFrameElement.getManifest","getManifest()")}} {{PlatformOnlyInline("Firefox OS", "2.5+")}}
- Retrieves the manifest of an app loaded in the browser {{HTMLElement("iframe")}} and returns it as JSON.
- {{domxref("HTMLIFrameElement.getScreenshot","getScreenshot()")}}
- Takes a screenshot of the browser {{HTMLElement("iframe")}}'s content. This is particularly useful to get thumbnails of tabs in a tabbed browser app.
- {{domxref("HTMLIFrameElement.getStructuredData","getStructuredData()")}} {{PlatformOnlyInline("Firefox OS", "2.5+")}}
- Retrieves any structured microdata (and hCard and hCalendar microformat data) contained in the HTML loaded in the browser {{HTMLElement("iframe")}} and returns it as JSON.
- {{domxref("HTMLIFrameElement.zoom","zoom()")}}
- Changes the zoom factor of the browser {{HTMLElement("iframe")}}'s content. This is particularly useful for zooming in/out on non-touch-enabled devices.
Specifications
| Specification | Status | Comment |
|---|---|---|
| {{SpecName('Referrer Policy', '#referrer-policy-delivery-referrer-attribute', 'referrer attribute')}} | {{Spec2('Referrer Policy')}} | Added the referrerPolicy property. |
| {{SpecName('HTML WHATWG', "the-iframe-element.html#the-iframe-element", "HTMLIFrameElement")}} | {{Spec2('HTML WHATWG')}} | The following property has been added: allowFullscreen. |
| {{SpecName('HTML5 W3C', "embedded-content-0.html#the-iframe-element", "HTMLIFrameElement")}} | {{Spec2('HTML5 W3C')}} | The following properties are now obsolete: scrolling, marginWidth, marginHeight, longDesc, frameBorder, and align.The following properties have been added: srcdoc, sandbox, seamless, and contentWindow. |
| {{SpecName('DOM2 HTML', 'html.html#ID-50708718', 'HTMLIFrameElement')}} | {{Spec2('DOM2 HTML')}} | The contentDocument property has been added. |
| {{SpecName('DOM1', 'level-one-html.html#ID-50708718', 'HTMLIFrameElement')}} | {{Spec2('DOM1')}} | Initial definition. |
Browser compatibility
{{CompatibilityTable}}
| Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
|---|---|---|---|---|---|
| Basic support | {{CompatVersionUnknown}} | {{CompatGeckoDesktop(1.0)}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} |
srcdoc |
4 | {{CompatGeckoDesktop(25)}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} |
sandbox |
4 | {{CompatGeckoDesktop(17)}}[1] | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} |
seamless {{experimental_inline}} |
4 | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} |
contentDocument |
{{CompatVersionUnknown}} | {{CompatVersionUnknown}} | 8.0[4] | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} |
contentWindow |
{{CompatUnknown}} | {{CompatUnknown}} | {{CompatVersionUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} |
allowFullScreen {{experimental_inline}} |
17 {{property_prefix("-webkit")}}[5] | {{CompatGeckoDesktop(9.0)}} {{property_prefix("-moz")}} {{CompatGeckoDesktop(18.0)}} |
{{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
referrerPolicy {{experimental_inline}} |
{{CompatNo}} | {{compatGeckoDesktop(42)}} [3] | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| Browser API methods | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| Feature | Android | Firefox Mobile (Gecko) | Firefox OS (Gecko) | IE Phone | Opera Mobile | Safari Mobile |
|---|---|---|---|---|---|---|
| Basic support | {{CompatVersionUnknown}} | {{CompatGeckoMobile(1.0)}} | 1.0.1 | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} |
srcdoc |
4 | {{CompatGeckoMobile(25)}} | 1.1 | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} |
sandbox |
4 | {{CompatGeckoMobile(17)}}[1] | 1.0.1 | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} |
seamless {{experimental_inline}} |
4 | {{CompatNo}} | {{CompatNo}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} |
contentDocument |
{{CompatVersionUnknown}} | {{CompatVersionUnknown}} | 1.0.1 | {{CompatUnknown}} | {{CompatVersionUnknown}} | {{CompatVersionUnknown}} |
contentWindow |
{{CompatUnknown}} | {{CompatUnknown}} | 1.0.1 | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} |
allowFullScreen {{experimental_inline}} |
17 {{property_prefix("-webkit")}}[5] | {{CompatGeckoMobile(9.0)}} {{property_prefix("-moz")}} {{CompatGeckoMobile(18.0)}} |
1.0.1 | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
referrerPolicy {{experimental_inline}} |
{{CompatNo}} | {{compatGeckoMobile(42)}}[3] | 2.5 | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
| Browser API methods | {{CompatNo}} | {{CompatNo}} | 1.0.1[2] | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
[1] Previously, the type of sandbox was a {{domxref("DOMString")}} instead of a {{domxref("DOMSettableTokenList")}}. This has been fixed with Gecko 29.0 {{geckoRelease(29)}}) ({{bug(845067)}}). Other browsers may still implement the property as DOMString since it was a late change in the specification.
[2] Requires privileged app, and browser and/or embed-apps permissions, depending on what you want to do. See Using the Browser API for more details. Most of the proprietary Browser API methods are supported from Firefox OS 1.0.1 onwards; they are marked where this is not the case.
[3] This property was named referrer from Firefox 42 to 44.
[4] For older version use HTMLIFrameElement.contentWindow.document instead.
[5] Daily test builds only.
See also
- The HTML element implementing this interface: {{HTMLElement("iframe")}}