Javascript event-based communication layer between DOM and iframe.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
dist Rebuilding Sep 18, 2018
src Adding backwards compat for some SpringRoll v1 features Sep 18, 2018
test bugfix: added back data that was missing from sendLater events Jul 12, 2018
.babelrc Fixed a issue where how Bellhop was building was breaking es6 classes Aug 2, 2018
.eslintrc es6: Added karma html testing Jun 5, 2018
.gitattributes Replace Ant build with Grunt tasks Nov 25, 2014
.gitignore es6: added dist to repo Jul 3, 2018
.jsbeautifyrc Reorganized code, added test, added formatting, bumped version Nov 4, 2015
.npmignore Add NPM ignore Nov 4, 2015
.prettierrc.js Adding prettier config to build process Aug 2, 2018
.travis.yml ES6: added run keyword to travis Jun 8, 2018
Bellhop.d.ts removed scoping from typescript definition file Aug 13, 2018
LICENSE Updated license and future NPM install Nov 4, 2015
bellhop-umd.js Rebuilding Sep 18, 2018 Rebuilding Sep 18, 2018
karma.conf.js ES6: Iframe testing working! Jun 5, 2018
package-lock.json Fixed a issue where how Bellhop was building was breaking es6 classes Aug 2, 2018
package.json updated version number Aug 10, 2018
rollup.config.js Adding prettier config to build process Aug 2, 2018

Bellhop Build Status Dependency Status

Bellhop is a simple event-based communication layer between the page DOM and an iframe. It doesn't require any additional dependencies. Super easy to use and setup.


npm install bellhop-iframe

Importing Bellhop

The Bellhop module contains support for ES6 modules, CommonJS and browser global definitions. To import with ES6,

import { Bellhop } from 'bellhop-iframe';

To import with CommonJS, refer instead to the UMD build

const Bellhop = require('bellhop-iframe/bellhop-umd.js');

You can also import the UMD version by using import

import 'bellhop-iframe/bellhop-umd.js';

Lastly, the UMD module can also be directly included on an HTML page. This will declare Bellhop and attach it directly to window

<script src="node_modules/bellhop-iframe/bellhop-umd.js"></script>

Basic Usage

Here's a very simple example to get started. We have two pages index.html and child.html.This is the minimum you need to start get them talking to each other.

Contents of index.html

<iframe src="child.html" id="page" width="200" height="200"></iframe>

// Create the bellhop object
const bellhop = new Bellhop();

// Pass in the iframe DOM object

// Listen for the 'init' event from the iframe
bellhop.on('init', function(event){
  // Handle the event here!

// Send data to the iframe
bellhop.send('user', {
  "name" : "Dave Smith",
  "age" : 16,
  "city" : "Boston"

Contents of child.html


// Create the bellhop object
const bellhop = new Bellhop();

// An example event to sent to the parent

// Handle events from the parent
bellhop.on('user', function(event){
  // Capture the data from the event
  const user =;

Available Methods

new Bellhop

The constructor creates a new Bellhop instance, taking an optional unique identifier for this instance. If no id is provided, a random one is selected


Connects a Bellhop instance to an iframe, or it's containing window. For instance, given a Bellhop instance bellhop:


will connect a child iframe to it's parent, allowing it to emit messages out of the iframe. However,

var iframe = document.querySelector('iframe');

allows a containing page to connect with an interior iframe and emit message into the iframe.


disconnect removes any listener for events from another frame, and stops listening for messages altogether


Sends a named message to another iframe:

bellhop.send('newHighscore', { value: 100 });

fetch and respond

Convenience methods for automating response of values between the interior and exterior of frames. For instance:

// parent.html
var iframe = document.querySelector('iframe');
var bellhop = new Bellhop(iframe);
bellhop.respond('config', { difficulty: 'hard', theme: 'dark' });

// child.html
var bellhop = new Bellhop();
bellhop.fetch('config', function(result) {
  console.log(result); // { difficulty: 'hard', theme: 'dark' }


Property for retrieving the iframe element through which this Bellhop instance is communicating:

var iframe = document.querySelector('iframe');
var bellhop = new Bellhop(iframe);

console.log( === iframe.contentWindow); // true


Copyright (c) 2018 Springroll

Released under the MIT License.