dashboard:controls embed event

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 event instead.

Payload

{
  "<controlId>": {
    "control": {},
    "value": "string | null",
    "asUrlSearchParam": "string | null",
    "urlId": "string"
  }
}

Properties

object

Control object keyed by the control’s ID.

Hide control properties

object

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

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.

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.

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

{
  "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"
  }
}

Getting started

Setup

App customization

Events & interactivity

Admin

dashboard:controls embed event

Payload

Properties

Replaying control state

Example

​Payload

​Properties

​Replaying control state

​Example

Payload

Properties

Replaying control state

Example