SandDance Embed is the easiest way to integrate SandDance into your custom app, via an <iframe> tag. SandDance Embed is a wrapper around SandDance Explorer, plus postMessage handlers to load data and manage its display from outside the iframe.


Development considerations

SandDance-Embed is an alternative to creating your own app wrapper around SandDance Explorer. Here are reasons you might choose one over the other:

  • SandDance Explorer will require an npm install and your own build / deployment system. You will be bound to use only compatible React versions. You will have greater control over events and injectable React sub-componentry.

  • SandDance Embed does not require an install or build system. Launch time might be slower as loads its own copy of React and other libraries at runtime. It runs in a sandbox mode which allows little customization.

Deployment scenarios

There are two ways to create a SandDance Embed iframe instance:

  1. Cross-domain
  2. In-domain

Cross-domain iframe

This is the simplest approach. Add an <iframe> tag in your HTML page:

<iframe id="embedIframe" src="" style="height:700px;width:100%"></iframe>

Get a code reference to this iframe:

const embedIframe = document.getElementById('embedIframe');
embedIframe.onload = () => {
    //ready to send commands to SandDance Embed

Note the version number in the address to specify by major version. You may style the iframe as you see fit.

Security: The URL is hosted by the secure SandDance GitHub Pages website.

Privacy: The page does not collect any data that you pass to SandDance Embed.

In-domain iframe

In your own website you can either download a copy of the sanddance-embed.html file and use it as above, or create an iframe dynamically.

Note the static html file approach will provide better performance, by utilizing the browser's built-in caching mechanisms to load scripts.

To dynamically create a SandDance Embed iframe in JavaScript:

    const embedPromise = new Promise((resolve, reject) => {
        const embedIframe = document.createElement('iframe'); = '700px'; = '1000px'
        embedIframe.onload = () => {
            const embedScript = embedIframe.contentDocument.createElement('script');
            embedScript.src = '';
            embedScript.onload = () => resolve(embedIframe);
            embedScript.onerror = reject;

This promise provides you embedIframe when it is available:

    embedPromise.then((embedIframe) => {
        //ready to send commands to SandDance Embed

Send commands to SandDance Embed

Use postMessage to communicate with embedIframe.contentWindow. For all command requests, see

  • Use the load command to load data and display initial chart:

    const data = [
        { x: 0, y: 0, z: 0 },
        { x: 1, y: 1, z: 1 },
        { x: 2, y: 2, z: 2 },
    embedIframe.contentWindow.postMessage({ action: 'load', data }, '*');

    The data variable can be an array, or a DataFile object.

    Notable optional parameters:

    • The props member, of type Explorer Props, here is shown used to specify the dark color theme, initially close the sidebar, and use the advanced renderer:
    const props = { theme: 'dark-theme', initialSidebarClosed: true, initialRenderer: { advanced: true } };
    embedIframe.contentWindow.postMessage({ action: 'load', data, props }, '*');

    Note that the props member is for initializing the instance of SandDance Explorer. A new dataset can be loaded with a subsequent load command, but props will be not be used.

    • The insight member, of type Insight, to specify a chart view:
    const insight = {
        chart: 'barchartH',
        columns: {
            y: 'Age',
            z: 'TicketCost',
            color: 'Class'
        scheme: 'category10',
        view: '3d',
    embedIframe.contentWindow.postMessage({ action: 'load', data, insight }, '*');
  • The getInsight command will request the current insight:

    embedIframe.contentWindow.postMessage({ action: 'getInsight' }, '*');
  • The theme command will get or set the theme:

    embedIframe.contentWindow.postMessage({ action: 'theme', dark: true }, '*');

Receive commands from SandDance Embed

Attach a listener to your own window to observe message passing:

    window.onmessage = (e) => {

The message will contain a property request which is a clone of the requesting message object which instigated the response. Other properties vary depending on the type of request. For all command responses, see

Here is an example of the response for getInsight:

    "request": {
        "action": "getInsight"
    "insight": {
        "colorBin": null,
        "columns": {
            "x": "x",
            "y": "y"
        "facetStyle": "wrap",
        "filter": null,
        "hideAxes": false,
        "hideLegend": false,
        "signalValues": {
            "RoleZ_ProportionSignal": 0.6,
            "Text_ScaleSignal": 1.2,
            "RoleColor_BinCountSignal": 7,
            "RoleColor_ReverseSignal": false,
            "Chart_PointScaleSignal": 5,
            "RoleZ_Grounded": false
        "size": {
            "height": 663,
            "width": 700
        "totalStyle": null,
        "transform": null,
        "chart": "scatterplot",
        "view": "2d"

For more information

Please visit the SandDance website.


  • Module
  • Object literal
  • Variable
  • Function
  • Function with type parameter
  • Index signature
  • Type alias
  • Type alias with type parameter
  • Enumeration
  • Enumeration member
  • Property
  • Method
  • Interface
  • Interface with type parameter
  • Constructor
  • Property
  • Method
  • Index signature
  • Class
  • Class with type parameter
  • Constructor
  • Property
  • Method
  • Accessor
  • Index signature
  • Inherited constructor
  • Inherited property
  • Inherited method
  • Inherited accessor
  • Protected property
  • Protected method
  • Protected accessor
  • Private property
  • Private method
  • Private accessor
  • Static property
  • Static method

Generated using TypeDoc