Rate this page:

JavaScript API


An iframe instance whose parent and child reside on different domains or hostnames constitutes a sandboxed environment. The contained page has no access to its parent. These restrictions are imposed by the browser's same origin policy.

There are a few limitations applicable to iframes:

  • Stylesheet properties from the parent do not cascade to the child page
  • Child pages have no access to its parent's DOM and JavaScript properties
  • Likewise, the parent has no access to its child's DOM or JavaScript properties

However, Atlassian Connect makes use of a technique called cross-domain messaging. This technique uses postMessage to pass data between the iframe and its parent.


Only content within an element with the class ac-content will be resized automatically. Content without this identifier is sized according to the body element, and is not dynamically resized. The recommended DOM layout for your app is:

<div class="ac-content">
    <p>Hello World</p>
    <div id="your-id-here">
        <p>Addon content goes here</p>

    ...this area reserved for our resize sensor divs

The resize sensor div is added on the iframe's load event. Removing the ac-content element after this, will prevent resizing from working correctly.

Sharing data between iframes

A single app can generate multiple iframes in a particular page in the target application. Depending on the use case for the app, the iframes may need to share information between each other.

The Atlassian Connect JavaScript client library, all.js, provides a publish/subscribe mechanism that you can use to exchange data between iframes.

A common scenario in which a single app presents multiple iframes in a page is where a web panel or other page element spawns a dialog box.

The only restriction on the data shared in this manner is that it must be serializable using the structured clone algorithm.

For more information on the event API visit the events documentation.

JavaScript client library

Atlassian Connect provides a JavaScript client library called all.js.


This library establishes the cross-domain messaging bridge with its parent. It also provides several methods and objects that you can use in your pages without making a trip back to your app server.

You must add the all.js script to your pages in order to establish the cross-domain messaging bridge. Make sure your pages include the following script:

<script src="https://connect-cdn.atl-paas.net/all.js"></script>

If you're using the atlassian-connect-express client library to build your app, this will automatically be inserted into your pages at run time.


Don't download the all.js file and serve it up from your app server directly. The all.js file must be served up by Atlassian in order for the cross-domain messaging bridge to be established.

The all.js file is only intended for use in an iframe inside an Atlassian product and does not work for standalone web pages.


The JavaScript client library has some configuration options for customizing its behavior. The options are passed using the data-options attribute.

<script src="https://connect-cdn.atl-paas.net/all.js" data-options="option1:value;option2:value"></script>

If you are using requirejs or other dynamic script loader, use an element with an id of ac-iframe-options in place of a script tag.

<div id="ac-iframe-options" data-options="option1:value;option2:value"></div>

The following options are currently supported:

resizetrue or falsetrueYou can deactivate the automatic resizing by setting resize=false.
sizeToParenttrue or falsefalse`With sizeToParent:true, the iframe will take up its parent's space (instead of being sized to its internal content).
margintrue or false`trueIf true, the margin option sets the body element's top, right and left margin to 10px for dialogs, and to 0 for non-dialog pages.
basetrue or falsefalseWith base:true, a base tag pointing to the host page is injected: . This can be useful for embedded links to product pages.

Debugging all.js

A non-compressed version of the all.js JavaScript can be viewed by replacing all.js with all-debug.js for example:

<script src="https://connect-cdn.atl-paas.net/all.js"></script>
<!-- replace with -->
<script src="https://connect-cdn.atl-paas.net/all-debug.js"></script>

This can be helpful when trying to trace errors or debug the app JavaScript.

To make all.js errors available to scripts running in your iframe (eg. front end monitoring such as Sentry or New Relic), you'll need to make a CORS request:

<script src="https://connect-cdn.atl-paas.net/all.js" crossorigin="anonymous"></script>

Note on URL Encoding

URL query parameters are encoded as application/x-www-form-urlencoded. This converts spaces to + which can cause issues when using JavaScript functions such as decodeURIComponent. A simple way to handle this is to convert + to %20 before decoding. A utility function decodeQueryComponent is provided for this purpose. For example:


Product cookbooks

For product-specific examples of what you can do through the front end JavaScript API that Connect provides, check out the Product cookbook.

Rate this page: