Child Page API

The Child API is for use on the page contained within the <iframe> tag. It is split into three sections. Settings 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.

Settings

The following Settings can be set from within the iframe page by creating a window.iframeResizer object on the page.

<script>
  window.iFrameResizer = {
    targetOrigin: "http://mydomain.com",
  }
</script>

With options that can be set in both the parent page and in the iframe, then the setting in the iframe takes preference.

offsetSize

default: undefined
type:    integer

Modify the computed size of the iframe. This is useful if the page in the iframe returns a size value that is constantly slightly different to how you want the iframe to be sized. This can be set to a positive or negative value.

Note: Setting this value in the iframe will override any value set in the parent page. Set to 0 to disable this option in the parent page.

sizeSelector

default: ''
type:    string

Use a CSS Selector to specify which element should be used to calculate the content size in the iframe. When the selector returns multiple elements, all of them are inspected and the largest value returned, every time time the page updates or resizes.

Alternatively you can directly add a data-iframe-size attribute to an element to achieve the same effect.

targetOrigin

default: '*'
type: string

This option allows you to restrict the domain of the parent page, to prevent other sites mimicking your parent page. This option is really a last line of defense and you should also setup a Content Security Policy on your web server.

Events

The following events can be included in the Settings object attached to the iframed page.

<script>
  window.iFrameResizer = {
    onReady: () => {
      // your code
    },
  }
</script>

onMessage

onMessage: (message) => void

Receive message posted from the parent page with the iframe.iframeResizer.sendMessage() method.

onReady

onReady: () => void

This function is called once iframe-resizer has been initialized after receiving a call from the parent page. If you need to call any of the following methods during page load, then they should be called from this event handler.

Methods

These methods are available in the iframe via the window.parentIframe object. These method should be contained by a test for the window.parentIframe object, in case the page is not loaded inside an iframe. For example:

if ("parentIframe" in window) {
  parentIframe.close();
}

autoResize(bool)

Turn autoResizing of the iframe on and off. Returns bool of current state.

close()

Remove the iframe from the parent page.

getId()

Returns the ID of the iframe that the page is contained in.

getParentOrigin()

Returns the Origin of the parent page.

getParentProps(callback)

Ask the containing page for its positioning coordinates. You need to provide a callback which receives an object with the following read only properties:

{
  // iframe.getBoundingRect()
  iframe: {
    width
    height
    top
    right
    bottom
    left
  },

  // from document.documentElement
  document: {
    scrollWidth
    scrollHeight
  },

  // window.visualViewport
  viewport: {
    width
    height
    offsetLeft
    offsetTop
    pageLeft
    pageTop
    scale
  }
}

Your callback function will be recalled when the parent page is scrolled or resized.

This method returns a disable() function, that you can call to stop updates from the parent page. The following example requests the properties from the parent page and passes a callback that logs them to the console and disables further updates.

function logParentProps() {
  const disableParentProps =
    parentIframe.getParentProps((parentProps) => {
      disableParentProps()
      console.log('Parent Props:', parentProps)
    })
}

scrollBy(x, y)

Scroll the parent page by the given amount.

scrollTo(x, y)

Scroll the parent page to the coordinates x and y.

scrollToOffset(x, y)

Scroll the parent page to the coordinates x and y relative to the position of the iframe.

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; to stop an attacker mimicking your parent page. See the MDN documentation on postMessage for more details.

resize()

Manually force iframe to resize. If for some reason a change in content size is not detected, this method allows you to nudge iframe-resizer to recalculate the page size.