post-frame

Tiny Javascript library for handling one-way cross-window communication between an iframe element and its parent window

Usage no npm install needed!

<script type="module">
  import postFrame from 'https://cdn.skypack.dev/post-frame';
</script>

README

post-frame

Tiny Javascript library for handling one-way cross-window communication between an iframe element and its parent window

Installation

Using npm

npm install post-frame --save

Usage

const postFrame = require('post-frame')

Methods

send( targetOrigin, events )

Registers event listeners in the embedded window for a given list of events. The event target is the Document. A postMessage to the specified origin is subsequently sent when a registered event is detected.

Note: This function must be invoked by the embedded window.

  • Parameters:

    • targetOrigin: The origin where message should be sent
      • Type: string
    • events: list of events that will invoke postMessage method
      • Type: array of strings
      • Note: The 'events' array should contain strings referencing common DOM Event types i.e. 'click' , 'mouseover'
  • Returns:

    • Type: function that removes all previously registered event listeners.

Example:

const postFrame = require('post-frame')

postFrame.send('http://someTargetOrigin.com', ['click', 'mouseover', 'wheel'])

receive( validOrigins, validEvents, fn )

Registers a 'message' event listener in parent window and invokes provided callback when a valid message from a valid origin is received. The event target is the Window.

Note: This function must be invoked by the parent window.

  • Parameters:

    • validOrigins: list of origins from which postMessages can be accepted
      • Type: string
    • validEvents: list of events to listen for in child window
      • Type: array of strings
    • fn: callback function to be invoked after message event has been validated
      • Type: callback
      • Note: An event argument (type string) indicating the type of event fired by child window can be optionally passed to callback
  • Returns:

    • Type: function that removes the registered 'message' event listener.

Example:

const postFrame = require('post-frame')

const validOrigins = [
  'http://someValidOrigin.com',
  'http://anotherValidOrigin.com'
]

postFrame.receive(validOrigins, ['click', 'mouseover', 'wheel'], event =>
  console.log(`Detected iframe event: ${event}`)
)