> ## 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:set-controls embed event

> Updates one or more controls on an embedded dashboard without a reload.

> [!NOTE]
>
> This event can only be processed by dashboards. Sending this event to an iframe that contains a non-dashboard Omni URL, such as an app, will have no effect on the embedded page.

Updates one or more controls on an embedded dashboard without a reload. Only controls included in the parameters are affected; any existing controls that aren't included retain their existing values.

```json theme={null}
{
  "name": "dashboard:set-controls",
  "payload": {
    "controlUrlParameters": ["string"]
  }
}
```

## Properties

**controlUrlParameters** `string[]`

An array of control specifications that define the control values to apply. Each entry is formatted as follows, url-encoded as it would appear in a signed embed URL:

```text theme={null}
c--<control_id>=<value>
```

Omni reads only the `c--` entries from each string. It drops anything else, including a filter parameter, a non-string entry, or an invalid entry. If a message doesn't have any control parameters, Omni ignores it.

> [!TIP]
>
> Retrieve values for this parameter by using Omni in a non-embedded context. Navigate to a dashboard with controls and change the control values, which changes the URL. Use what's in the URL as the value for this parameter.

## When to send this event

Send this event after Omni emits [`page:ready`](https://docs.omni.co/embed/events/page-ready) or [`dashboard:ready`](https://docs.omni.co/embed/events/dashboard-ready). To apply controls each time a dashboard loads, send this event in response to `dashboard:ready`.

If the dashboard isn't ready when the event arrives, Omni keeps the event and applies it when the dashboard is ready:

* **If you send more than one event**, Omni applies the events in the order that you sent them. If two events set the same control, the later event wins.
* **If you send a [`navigate`](https://docs.omni.co/embed/events/navigate) event**, Omni discards the controls that wait for the page the user leaves.
* **If you send this event after a `navigate` event**, Omni applies the controls to the dashboard where the navigation arrives.

## Example

This example sets a field switcher control and a top N control directly:

```javascript wrap theme={null}
const iframe = document.querySelector("iframe#omni-dashboard")

iframe.contentWindow.postMessage(
  {
    name: "dashboard:set-controls",
    payload: {
      controlUrlParameters: [
        // field switcher / timeframe control: swap the field
        "c--8f2c1e7a=users.created_at%5Bquarter%5D",
        // top N control
        "c--3b9d4f10=10",
      ],
    },
  },
  "https://yourcompany.embed-omniapp.co"
)
```

### Save and replay control state

This example saves the control state Omni reports for the dashboard, then replays it later:

```javascript wrap theme={null}
let savedControls = null

window.addEventListener("message", (event) => {
  if (event.data?.name === "dashboard:controls") {
    savedControls = event.data.payload
  }
})

function restoreControls() {
  iframe.contentWindow.postMessage(
    {
      name: "dashboard:set-controls",
      payload: {
        controlUrlParameters: Object.values(savedControls)
          .map((control) => control.asUrlSearchParam)
          .filter((parameter) => parameter !== null),
      },
    },
    "https://yourcompany.embed-omniapp.co"
  )
}
```


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