> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# dashboard:control-changed embed event

> Emitted by Omni when the value of one or more controls on an embedded dashboard changes.

Emitted by Omni when the value of one or more controls on an embedded dashboard changes. The payload has only the controls that changed, so your page can react to a single control without comparing two [`dashboard:controls`](https://docs.omni.co/embed/events/dashboard-controls) payloads.

Omni sends this event right after the `dashboard:controls` event that it compares, and only when at least one control changed:

* **When the dashboard loads**, every control is reported as `added`. A dashboard with no controls doesn't send this event.
* **When a parent control changes**, each child control whose value follows the parent is also reported as `updated`.
* **When only the URL changes**, such as a new `asUrlSearchParam` for a child control or a new `urlId`, Omni doesn't send this event. The value didn't change. Omni still sends a new `dashboard:controls` event.

## Payload

```json theme={null}
{
  "<controlId>": {
    "action": "added | removed | updated",
    "prev": {
      "control": {},
      "value": "string | null",
      "asUrlSearchParam": "string | null"
    },
    "next": {
      "control": {},
      "value": "string | null",
      "asUrlSearchParam": "string | null"
    },
    "urlId": "string"
  }
}
```

## Properties

**controlId** `object`

Change object keyed by the control's ID.

**change properties**

**action** `string`

The type of control change:

* `added` - The control was added, or the dashboard loaded
* `removed` - The control was removed
* `updated` - The control's value changed. Multi-field filter and dynamic filter controls don't have a value (it is always `null`), so they are reported as `updated` when the control itself changes.

**prev** `object`

The control as the previous `dashboard:controls` event reported it, with `control`, `value`, and `asUrlSearchParam`. Refer to [`dashboard:controls`](https://docs.omni.co/embed/events/dashboard-controls#properties) for a description of each property. Not included for `added` controls.

**next** `object`

The control as this `dashboard:controls` event reports it, with `control`, `value`, and `asUrlSearchParam`. Not included for `removed` controls.

**urlId** `string`

ID of the dashboard used in the URL.

## Example

This example shows a timeframe control that changed from month to week:

```json wrap theme={null}
{
  "createdAtTimeframe": {
    "action": "updated",
    "prev": {
      "control": {
        "id": "createdAtTimeframe",
        "type": "FIELD_SELECTION",
        "kind": "TIMEFRAME",
        "field": "order_items.created_at[month]",
        "label": "Created At",
        "options": [
          { "label": "Month", "value": "order_items.created_at[month]" },
          { "label": "Week", "value": "order_items.created_at[week]" }
        ]
      },
      "value": "order_items.created_at[month]",
      "asUrlSearchParam": "c--createdAtTimeframe=order_items.created_at%5Bmonth%5D"
    },
    "next": {
      "control": {
        "id": "createdAtTimeframe",
        "type": "FIELD_SELECTION",
        "kind": "TIMEFRAME",
        "field": "order_items.created_at[week]",
        "label": "Created At",
        "options": [
          { "label": "Month", "value": "order_items.created_at[month]" },
          { "label": "Week", "value": "order_items.created_at[week]" }
        ]
      },
      "value": "order_items.created_at[week]",
      "asUrlSearchParam": "c--createdAtTimeframe=order_items.created_at%5Bweek%5D"
    },
    "urlId": "0f238b75"
  }
}
```

This example listens for the event and logs the new value of each control that changed:

```javascript wrap theme={null}
window.addEventListener("message", (event) => {
  if (event.origin !== "https://yourcompany.embed-omniapp.co") return
  if (event.data?.name !== "dashboard:control-changed") return

  for (const [controlId, change] of Object.entries(event.data.payload)) {
    if (change.action === "removed") {
      console.log(`${controlId} was removed`)
    } else {
      console.log(`${controlId} is now ${change.next.value}`)
    }
  }
})
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.