> ## 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-filters embed event

> Triggers the change of a filter value on an embedded dashboard.

> [!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.

Triggers the change of a filter value on an embedded dashboard. Only filters included in the parameter are affected; any existing filters that aren't included will retain their existing values.

This event and [`dashboard:filter-change-by-url-parameter`](https://docs.omni.co/embed/events/dashboard-filter-change-by-url-parameter) are synonyms. They take the same payload and Omni handles them the same way.

```json theme={null}
{
  "name": "dashboard:set-filters",
  "payload": {
    "filterUrlParameter": "string"
  }
}
```

## 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 filters 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 filter, the later event wins.
* **If you send a [`navigate`](https://docs.omni.co/embed/events/navigate) event**, Omni discards the filters that wait for the page the user leaves.
* **If you send this event after a `navigate` event**, Omni applies the filter to the dashboard where the navigation arrives.

## Properties

**filterUrlParameter** `string`

A filter specification object that defines the filter values to apply. Filter specifications are formatted as follows:

```
f--<filter_id>={"values":["value1","value2", ...]}
```

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

## Example

```json wrap theme={null}
{
  "name": "dashboard:set-filters",
  "payload": {
    "filterUrlParameter": "f--order_items.status=%7B"appliedLabels"%3A%7B%7D%2C"values"%3A%5B"Complete"%5D%7D"
  }
}
```


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