We're looking for a user researcher to understand the needs of developers and designers. Is this you or someone you know? Check out the post: https://mzl.la/2IGzdXS

The HTMLIFrameElement interface provides special properties and methods (beyond those of the 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, HTMLElement.

HTMLIFrameElement.align
Is a DOMString that specifies the alignment of the frame with respect to the surrounding context.
HTMLIFrameElement.allow
Is a list of origins the the frame is allowed to display content from. This attribute also accepts the values self and src which represent the origin in the iframe's src attribute. The default value is src.
HTMLIFrameElement.allowfullscreen
Is a Boolean indicating whether the inline frame is willing to be placed into full screen mode. See Using full-screen mode for details.
HTMLIFrameElement.allowPaymentRequest
Is a Boolean indicating whether the Payment Request API may be invoked inside a cross-origin iframe.
HTMLIFrameElement.contentDocument Read only
Returns a Document, the active document in the inline frame's nested browsing context.
HTMLIFrameElement.contentWindow Read only
Returns a WindowProxy, the window proxy for the nested browsing context.
HTMLIFrameElement.csp
Specifies the Content Security Policy that an embedded document must agree to enforce upon itself.
HTMLIFrameElement.frameBorder
Is a DOMString that indicates whether to create borders between frames.
HTMLIFrameElement.height
Is a DOMString that reflects the height HTML attribute, indicating the height of the frame.
HTMLIFrameElement.longDesc
Is a DOMString that contains the URI of a long description of the frame.
HTMLIFrameElement.marginHeight
Is a DOMString being the height of the frame margin.
HTMLIFrameElement.marginWidth
Is a DOMString being the width of the frame margin.
HTMLIFrameElement.name
Is a DOMString that reflects the name HTML attribute, containing a name by which to refer to the frame.
HTMLIFrameElement.referrerPolicy
Is a DOMString that reflects the referrerpolicy HTML attribute indicating which referrer to use when fetching the linked resource.
HTMLIFrameElement.sandbox
Is a DOMSettableTokenList that reflects the sandbox HTML attribute, indicating extra restrictions on the behavior of the nested content.
HTMLIFrameElement.scrolling
Is a DOMString that indicates whether the browser should provide scrollbars for the frame.
HTMLIFrameElement.src
Is a DOMString that reflects the src HTML attribute, containing the address of the content to be embedded.
HTMLIFrameElement.srcdoc
Is a DOMString that represents the content to display in the frame.
HTMLIFrameElement.width
Is a DOMString that reflects the width HTML attribute, indicating the width of the frame.

Methods

Inherits properties from its parent, HTMLElement.

Browser API methods

To support the requirement of a browser <iframe>, HTMLIFrameElement has been extended with new methods that give the <iframe> some super powers. These are non-standard (see Browser compatibility.)

The following navigation methods allow navigation through the browsing history of the <iframe>. They are necessary to be able to implement back, forward, stop, and reload buttons.

HTMLIFrameElement.reload()
Allows reloading of the <iframe> element content.
HTMLIFrameElement.stop()
Allows stopping of the <iframe>'s content loading.
HTMLIFrameElement.getCanGoBack()
Indicates whether it's possible to navigate backwards.
HTMLIFrameElement.goBack()
Changes the location of the <iframe> for the previous location in its browsing history.
HTMLIFrameElement.getCanGoForward()
Indicates whether it's possible to navigate forward.
HTMLIFrameElement.goForward()
Changes the location of the <iframe> for the next location in its browsing history.

Management methods

The next set of methods manage the resources used by a browser <iframe>. These are especially useful for implementing tabbed browser application.

HTMLIFrameElement.executeScript()
Allows a specified script to be executed against a page loaded in the browser <iframe>.
HTMLIFrameElement.purgeHistory()
Clears all the resources (cookies, localStorage, cache, etc.) associated with the browser <iframe>.
HTMLIFrameElement.setVisible()
Changes the visibility state of a browser <iframe>. This can influence resource allocation and some function usage such as requestAnimationFrame.
HTMLIFrameElement.getVisible()
Indicates the current visibility state of the browser <iframe>.
HTMLIFrameElement.setActive()
Sets the current <iframe> as the active frame, which has an effect on how it is prioritized by the process manager.
HTMLIFrameElement.getActive()
Indicates whether the current browser <iframe> is the currently active frame.

The following methods allow direct control of sound in the browser element.

HTMLIFrameElement.getVolume()
Gets the current volume of the browser <iframe>.
HTMLIFrameElement.setVolume()
Sets the current volume of the browser <iframe>.
HTMLIFrameElement.mute()
Mutes any audio playing in the browser <iframe>.
HTMLIFrameElement.unmute()
Unmutes any audio playing in the browser <iframe>.
HTMLIFrameElement.getMuted()
Indicates whether the browser <iframe> is currently muted.

Search methods

New methods are provided to allow programmatic searches of browser <iframe>s to be carried out.

HTMLIFrameElement.findAll()
Searches for a string in a browser <iframe>'s content; if found, the first instance of the string relative to the caret position will be highlighted.
HTMLIFrameElement.findNext()
Highlights the next or previous instance of a search result after a findAll() search has been carried out.
HTMLIFrameElement.clearMatch()
Clears any content highlighted by findAll() or findNext().

In order to manage the browser <iframe>'s content, many new events were added (see below). The following methods are used to deal with those events:

The <iframe> gains support for the methods of the EventTarget interface
addEventListener(), removeEventListener(), and dispatchEvent().
HTMLIFrameElement.sendMouseEvent()
Sends a MouseEvent to the <iframe>'s content.
HTMLIFrameElement.sendTouchEvent()
Sends a TouchEvent to the <iframe>'s content. Note that this method is available for touch enabled devices only.
HTMLIFrameElement.addNextPaintListener()
Defines a handler to listen for the next MozAfterPaint event in the browser <iframe>.
HTMLIFrameElement.removeNextPaintListener()
Removes a handler previously set with addNextPaintListener().

Utility methods

Last, there are some utility methods, useful for apps that host a browser <iframe>.

HTMLIFrameElement.download()
Downloads a specified URL, storing it at the specified filename/path.
HTMLIFrameElement.getContentDimensions()
Retrieves the X and Y dimensions of the content window.
HTMLIFrameElement.getManifest()
Retrieves the manifest of an app loaded in the browser <iframe> and returns it as JSON.
HTMLIFrameElement.getScreenshot()
Takes a screenshot of the browser <iframe>'s content. This is particularly useful to get thumbnails of tabs in a tabbed browser app.
HTMLIFrameElement.getStructuredData()
Retrieves any structured microdata (and hCard and hCalendar microformat data) contained in the HTML loaded in the browser <iframe> and returns it as JSON.
HTMLIFrameElement.zoom()
Changes the zoom factor of the browser <iframe>'s content. This is particularly useful for zooming in/out on non-touch-enabled devices.

Specifications

Specification Status Comment
Feature Policy
The definition of 'allow' in that specification.
Draft Adds allow property.
Payment Request API
The definition of 'allowPaymentRequest' in that specification.
Candidate Recommendation Adds allowPaymentRequest property.
Referrer Policy
The definition of 'referrer attribute' in that specification.
Candidate Recommendation Added the referrerPolicy property.
HTML Living Standard
The definition of 'HTMLIFrameElement' in that specification.
Living Standard The following property has been added: allowFullscreen.
HTML5
The definition of 'HTMLIFrameElement' in that specification.
Recommendation The following properties are now obsolete: scrolling, marginWidth, marginHeight, longDesc, frameBorder, and align.
The following properties have been added: srcdoc, sandbox, and contentWindow.
Document Object Model (DOM) Level 2 HTML Specification
The definition of 'HTMLIFrameElement' in that specification.
Obsolete The contentDocument property has been added.
Document Object Model (DOM) Level 1 Specification
The definition of 'HTMLIFrameElement' in that specification.
Obsolete Initial definition.

Browser compatibility

FeatureChromeEdgeFirefoxInternet ExplorerOperaSafari
Basic support Yes Yes1 Yes Yes Yes
addNextPaintListener No No471 No No No
align43 Yes Yes ? Yes6
allow60 ? ? ?53 ?
allowFullScreen17 webkit 2 Yes

18

9 moz

No No No
allowPaymentRequest601556 ? No ?
clearMatch No No471 No No No
contentDocument43 Yes Yes8 Yes10
contentWindow43 Yes Yes Yes Yes6
csp61 ? ? ?48 ?
download No No471 No No No
executeScript No No471 No No No
findAll No No471 No No No
findNext No No471 No No No
frameBorder43 Yes Yes ? Yes6
getActive No No471 No No No
getCanGoBack No No471 No No No
getCanGoForward No No471 No No No
getContentDimensions No No471 No No No
getManifest No No471 No No No
getMuted No No471 No No No
getScreenshot No No471 No No No
getStructuredData No No471 No No No
getVisible No No471 No No No
getVolume No No471 No No No
goBack No No471 No No No
goForward No No471 No No No
height43 Yes Yes ? Yes6
longDesc43 Yes Yes ? Yes6
marginHeight43 Yes Yes ? Yes6
marginWidth43 Yes Yes ? Yes6
mute No No471 No No No
name43 Yes Yes ? Yes6
purgeHistory No No471 No No No
referrerPolicy53 ?50 ?38 ?
reload No No471 No No No
removeNextPaintListener No No471 No No No
sandbox43 Yes173 ? ?6
scrolling43 Yes Yes ? Yes6
sendMouseEvent No No471 No No No
sendTouchEvent No No471 No No No
setActive No No471 No No No
setVisible No No471 No No No
setVolume No No471 No No No
src43 Yes Yes ? ?6
srcdoc43 Yes25 No ?6
stop No No471 No No No
unmute No No471 No No No
width43 Yes Yes ? Yes6
zoom No No471 No No No
FeatureAndroid webviewChrome for AndroidEdge mobileFirefox for AndroidOpera AndroidiOS SafariSamsung Internet
Basic support Yes Yes Yes4 Yes ? ?
addNextPaintListener No No No No No No ?
align Yes Yes ? ? Yes ? ?
allow6666 ? ?53 ? ?
allowFullScreen17 webkit 217 webkit 2 Yes

18

9 moz

No ? ?
allowPaymentRequest No61 ? ? No ? ?
clearMatch No No No No No No ?
contentDocument Yes Yes ?4 Yes Yes ?
contentWindow Yes Yes Yes Yes Yes Yes ?
csp6161 ? ?48 ? ?
download No No No No No No ?
executeScript No No No No No No ?
findAll No No No No No No ?
findNext No No No No No No ?
frameBorder Yes Yes ? ? Yes ? ?
getActive No No No No No No ?
getCanGoBack No No No No No No ?
getCanGoForward No No No No No No ?
getContentDimensions No No No No No No ?
getManifest No No No No No No ?
getMuted No No No No No No ?
getScreenshot No No No No No No ?
getStructuredData No No No No No No ?
getVisible No No No No No No ?
getVolume No No No No No No ?
goBack No No No No No No ?
goForward No No No No No No ?
height Yes Yes ? ? Yes ? ?
longDesc Yes Yes ? ? Yes ? ?
marginHeight Yes Yes ? ? Yes ? ?
marginWidth Yes Yes ? ? Yes ? ?
mute No No No No No No ?
name Yes Yes ? ? Yes ? ?
purgeHistory No No No No No No ?
referrerPolicy5151 ?5038 ? ?
reload No No No No No No ?
removeNextPaintListener No No No No No No ?
sandbox44 Yes173 ? ? ?
scrolling Yes Yes ? ? Yes ? ?
sendMouseEvent No No No No No No ?
sendTouchEvent No No No No No No ?
setActive No No No No No No ?
setVisible No No No No No No ?
setVolume No No No No No No ?
src Yes Yes ? ? ? ? ?
srcdoc44 Yes25 ? ? ?
stop No No No No No No ?
unmute No No No No No No ?
width Yes Yes ? ? Yes ? ?
zoom No No No No No No ?

1. Supported in chrome code only.

2. Daily test builds only.

3. Previously, the type of sandbox was a DOMString instead of a DOMSettableTokenList. This has been fixed with Firefox 29. Other browsers may still implement the property as DOMString since it was a late change in the specification.

See also

  • The HTML element implementing this interface: <iframe>

Document Tags and Contributors

Last updated by: fscholz,