> For the complete documentation index, see [llms.txt](https://docs.sprinkledata.com/product/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sprinkledata.com/product/analysing-your-data/dashboards/embed-events.md).

# Embed events

### Overview

You can embed a Sprinkle Dashboard directly inside your web application using an **iframe.**\
To make the dashboard interactive with your app, Sprinkle provides a **postMessage bridge.**

This bridge allows the dashboard to send real-time events (like chart clicks, table row clicks, or filter changes) to your parent application.\
Your app can **listen to these events** and take appropriate actions — for example, updating UI components or triggering API calls.

### **1. Setting Up the Event Bridge**

The Sprinkle dashboard sends messages from the iframe to the parent page using the standard browser `postMessage` API.

#### **How It Works**

* **Direction:** One-way communication by default — from the iframe → parent page.
* **Extension:** Can be expanded for two-way communication if needed.

#### **Example Setup**

Add this listener to your parent application:

```
// Listen for all events from the dashboard iframe
window.addEventListener("message", (event) => {
  // Optional: validate origin
  // if (event.origin !== "https://sprinkledata_example.com") return;

  const { type, payload, source } = event.data || {};

  if (source !== "SPRINKLE-DASHBOARD") return;

  console.log("Dashboard Event:", type, payload);
});
```

### **2. Event Structure**

Each event sent from the dashboard follows this structure:

```
{
  "source": "SPRINKLE-DASHBOARD",
  "type": "EVENT_TYPE",
  "payload": {
    ...eventData
  }
}
```

#### **Field Descriptions**

| Field     | Description                                               |
| --------- | --------------------------------------------------------- |
| `source`  | Always `"SPRINKLE-DASHBOARD"` — identifies the sender     |
| `type`    | The event type (e.g., `FILTERS_UPDATE`, `CHART_ON_CLICK`) |
| `payload` | JSON object containing event-specific data                |

### 3. Event Types

The dashboard currently emits the following events:

{% tabs %}
{% tab title="FILTERS\_UPDATE" %}
This event is triggered with this structural data payload when the page loads or when filters are applied by clicking the Apply button.

```
{
  data: {
    [filter_id]: {
      ...(specific_filter_full_data)
    }
    ...
  }
}

```

{% endtab %}

{% tab title="FILTER\_ON\_CHANGE" %}
This event is triggered with this structural data payload when any  filter, variable is changed

```
{
  data: {
    filter: {
      id,
      value,
      …
    },
    updatedFilters: {
     [filter_id]: {
      ...(specific_filter_full_data)
     }
     ...
    }
  }
}
```

{% endtab %}

{% tab title="TABLE\_ON\_CLICK" %}
This event is triggered with this structural data payload when table row is clicked.

```
{
  data: {
    tableData: {
      ...(table_all_required_data)
    }
    ...
  }
}
```

{% endtab %}

{% tab title="CHART\_ON\_CLICK" %}
This event is triggered with this structural data payload when chart item is clicked

```
{
  data: {
    chartData: {
      ...(chart_all_required_data)
    }
    ...
  },
  events: chart_events
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
You can request additional custom events from us if your use case requires them.
{% endhint %}

### **4. Event Payload Details**

* All payloads are **JSON-safe objects**.
* Only **serializable data** is sent — no raw DOM references or native event objects (for security reasons).
* You can safely log or parse the payload in your app.

### **5. Example: Handling Dashboard Events in Your App**

Here’s a complete example of how to listen for and handle different dashboard events:

```
window.addEventListener("message", (event) => {
  const { type, payload, source } = event.data || {};
  if (source !== "SPRINKLE-DASHBOARD") return;

  switch (type) {
    case "FILTERS_UPDATE":
      console.log("Filters applied or loaded:", payload);
      break;

    case "CHART_ON_CLICK":
      console.log("Chart clicked:", payload.data.activeViz);
      console.log("Chart data:", payload.data.chartData);
      console.log("Event info:", payload.events);
      break;

    default:
      console.warn("Unknown event type:", type);
  }
});

```