Parent Page API

The Parent API is for use on the page containing the <iframe> tag. It is split into three sections. Options contains settings that can be passed when calling iframe-resizer. Events are triggered by updates to the iframe, or messages from the iframe. Methods allow you to interact with iframe-resizer after the initial resizing.

Options

The following options can be passed to iframe-resizer on the parent page.

License

type:    string

Commercial Enter the key provided with the purchased commercial license.

Open Source If you are using iframe-resizer on an open-source site or project, then you can use it for free under the terms of the Gnu Public License V3. To accept these terms set the license to GPLv3.

bodyBackground

default: null
type:    string

Override the body background style in the iframe.

bodyMargin

default: null
type:    string || number

Override the default body margin style in the iframe. A string can be any valid value for the CSS margin attribute, for example ‘8px 3em’. A number value is converted into px.

bodyPadding

default: null
type:    string || number

Override the default body padding style in the iframe. A string can be any valid value for the CSS margin attribute, for example ‘8px 3em’. A number value is converted into px.

checkOrigin

default: true
type:    boolean || array

When set to true, only allow incoming messages from the domain listed in the src property of the iframe tag. If your iframe navigates between different domains, ports or protocols; then you will need to provide an array of URLs or disable this option.

direction

default: 'vertical'
values: 'horizontal' || 'vertical' || 'none'

Set the direction in which you want the iframe to automatically scale to the content size.

inPageLinks

default: false
type:    boolean

When enabled in page linking inside the iframe and from the iframe to the parent page will be enabled.

^* This option is available in the Professional, Business and Open-source editions.

offset

default: 0
type:    integer

Modify the computed size of the iframe. This is useful if the page in the iframe returns a size value that is consitantly slightly different to how you want the iframe to be sized.

^* This value can also be set on a per page basis in the iframe.

scrolling

default: false
type:    boolean | 'omit'

Enable scroll bars in iframe.

true applies scrolling="yes"
false applies scrolling="no"
’omit’ applies no scrolling attribute to the iframe

tolerance

default: 0
type:    integer

Set the number of pixels the iframe content size has to change by, before triggering a resize of the iframe.

waitForLoad

default: false
type:    boolean

By default iframe-resizer sends a message to the iframe as soon as it is called, and then tries again when the onload event of the iframe is triggered. Setting this option to true will disable the first attempt to contact the iframe and force it to wait for the load event to fire. This is useful with some web frameworks that create the iframe after the main webpage has loaded.

warningTimeout

default: 5000
type:    integer

Set the number of milliseconds after which a warning is logged if the iframe has not responded. Set to 0 to suppress warning messages of this type.

Events

The following callback events can be passed to iframe-resizer on the parent page, as part of the options object.

onClose

onClose: (iframeID) => boolean;

Called before the iframe is closed via parentIframe.close() method. Returning false will prevent the iframe from closing.

onClosed

onClosed: (iframeID) => undefined;

Called after the iframe is closed via parentIframe.close() method.

onMessage

onMessage: ({ iframe, message }) => undefined;

Receives messages posted from the iframe with the parentIframe.sendMessage() method.

onMouseEnter

onMouseEnter: ({ iframe, height, width, type }) => undefined;

Function called after the mouse enters the iframe. Passes messageData object containing the iframe, screenX, screenY and the type of event that triggered the callback.

onMouseLeave

onMouseLeave: ({ iframe, height, width, type }) => undefined;

Function called after the mouse leaves the iframe. Passes messageData object containing the iframe, screenX, screenY and the type of event that triggered the callback.

onReady

onReady: (iframe) => undefined;

Called after initial setup.

onResized

onResized: ({ iframe, height, width, type }) => undefined;

Function called after iframe resized. Passes messageData object containing the iframe, height, width and the type of event that triggered the iframe to resize.

onScroll

onScroll: ({ iframe, top, left, }) => [true | false];

Called before the page is repositioned after a request from the iframe, due to either an in page link, or a direct request from either parentIframe.scrollTo() or parentIframe.scrollToOffset(). If this function returns false, it will stop the library from repositioning the page, so that you can implement your own custom scrolling instead.

The following example shows how to adjust the scroll point. This can be useful if you have a sticky header on your page and you need ensure the target scroll point does not get covered by your header.

const SCROLL_OFFSET = 50

iframeResize({
  onScroll: ({ top, left }) {
    window.scrollTo({
      top: top + SCROLL_OFFSET,
      left,
      behavior: 'auto'
    })

    return false // Stop iframe-resizer scrolling the page
  }
})

Methods

Once the iframe has been initialized, an iframeResizer object is bound to it. This has the following methods available.

disconnect()

Disconnect iframe-resizer from the iframe. This method MUST to be called, before removing an iframe from the page.

moveToAnchor(anchor)

Move to anchor in the iframe.

resize()

Tell the iframe to resize itself.

sendMessage(message, [targetOrigin])

Send data to the containing page, message can be any data type that can be serialized into JSON. The targetOrigin option is used to restrict where the message is sent to, in case your iframe navigates away to another domain.