> ## 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.

# app:filter-changed embed event

> Emitted by Omni when an embedded app changes the filters on one of its queries.

Omni emits `app:filter-changed` when an embedded [app](/visualize-present/apps) changes a filter on one of its queries after the app loads. An app changes filters through its own controls, which call `omni.query(name).setFilter()` and `.removeFilter()` in the app's code.

Use this to keep your own interface in sync with what someone has filtered to inside the app.

<Note>
  Embedded apps are in beta. Contact Omni support to enable them.
</Note>

## Payload

```json theme={null}
{
  "name": "app:filter-changed",
  "payload": {
    "filters": {},
    "changed": []
  }
}
```

## Properties

<ParamField path="filters" type="object">
  The complete set of filter overrides after the change, as an object of query name to field name to value. A query with no overrides is absent.
</ParamField>

<ParamField path="changed" type="array">
  What differs from the previous state. One entry per changed field.

  <Expandable title="changed properties" defaultOpen="true">
    <ParamField path="queryName" type="string">
      The name of the app query whose filter changed.
    </ParamField>

    <ParamField path="field" type="string">
      The fully-qualified field name the filter applies to.
    </ParamField>

    <ParamField path="action" type="string">
      The type of change:

      * `added` - A filter was set on a field that had none
      * `removed` - An existing filter was removed
      * `updated` - An existing filter's value changed
    </ParamField>

    <ParamField path="prev" type="unknown">
      The previous filter value. Absent when `action` is `added`.
    </ParamField>

    <ParamField path="next" type="unknown">
      The new filter value. Absent when `action` is `removed`.
    </ParamField>
  </Expandable>
</ParamField>

## Example

Someone picks **Returned** in an app's status control, and the app calls `setFilter` on its `orders` query:

```json theme={null}
{
  "name": "app:filter-changed",
  "payload": {
    "filters": {
      "orders": {
        "order_items.status": "Returned"
      }
    },
    "changed": [
      {
        "queryName": "orders",
        "field": "order_items.status",
        "action": "updated",
        "prev": "Complete",
        "next": "Returned"
      }
    ]
  }
}
```

Values are the raw filter values the app passes to `setFilter` — a scalar, an array, or a filter object — so treat them as opaque unless you know what the app sends.

Refer to [Consuming events](/embed/events/consume) for the full listener setup, including origin checks.