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

> Emitted by Omni with an embedded dashboard's control state, on load and whenever it changes.

Emitted by Omni when an embedded dashboard loads and again whenever its control configuration changes. The payload lists every control on the dashboard — including controls with no URL value — so your page can build its own control UI or save the state for later.

The event reports the dashboard's current control selection, as resolved from the URL. On a dashboard that doesn't run automatically, the selection can be ahead of the tiles until the user clicks **Run**. Viewer-added filters are carried by the [`dashboard:filters`](https://docs.omni.co/embed/events/dashboard-filters) event instead.

## Payload

```json theme={null}
{
  "<controlId>": {
    "control": {},
    "value": "string | null",
    "asUrlSearchParam": "string | null",
    "urlId": "string"
  }
}
```

## Properties

**controlId** `object`

Control object keyed by the control's ID.

**control properties**

**control** `object`

The full control object. Its shape depends on `control.type`; only field switchers, multi-field pickers, and parent controls carry `options`.

**value** `string | null`

The control's current value as a string, or `null` when the control has no URL value — multi-field filters and dynamic filters, for example. Period-over-period controls encode their value as JSON. An empty string is a value in its own right — a field picker with everything deselected — and is not the same as `null`.

**asUrlSearchParam** `string | null`

The control as a URL search param. Join the params from every control to build a dashboard URL with the control state applied. `null` when there is nothing to replay, such as the control not having a URL value or a parent control already reproduces it. Skip those rather than joining them.

**urlId** `string`

ID of the dashboard used in the URL.

## Replaying control state

Each entry's `asUrlSearchParam` is the `c--` search parameter that reproduces the control's value. To save a view, join the non-`null` parameter; to restore it, pass them back when you generate the embed URL — for example through the SDK's `filterSearchParam` property — or append them to a dashboard URL.

A child control that follows a parent control has a `null` parameter on purpose. In this case, the parent's own parameter reproduces it, and an explicit child parameter wins over the parent on replay, which would stop the child from following later parent changes.

## Example

```json wrap theme={null}
{
  "createdAtTimeframe": {
    "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",
    "urlId": "0f238b75"
  }
}
```


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