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

# Save and restore dashboard filters and controls in embedded apps

> Use embed events to capture a user's dashboard filter and control selections, store them, and reapply them later so users can return to the views they've customized.

[All guides](https://docs.omni.co/guides.md)

Progress

%

Category

embed

Last updated

November 2026

# Save and restore dashboard filters and controls in embedded apps

Users who filter or configure an embedded dashboard lose that view the moment they navigate away or close the tab. This guide walks through capturing a user's filter and control selections with embed events, storing them outside the dashboard, and reapplying them later, so users can build a set of views they return to without redoing that work every time. It also covers what's possible, and what isn't, for embedded apps.

This is especially relevant if:

* You embed dashboards in your application and want users to save and switch between multiple configured views of the same dashboard
* You want those preferences to persist across browser sessions or devices, not just within a single page load
* You're building save, rename, duplicate, or delete controls for saved views around an embedded dashboard or app

## How persistence works

The pattern has two halves: your application listens for state events coming out of the dashboard, and your application sends that state back into the dashboard on demand. Between those two steps, you decide where saved configurations live and how they're matched back up with what's currently on screen.

Dashboards have two kinds of state worth saving, and Omni treats them as separate systems with separate events: filters a viewer sets, and controls (field switchers, timeframe pickers, top N selectors, and similar) built into the dashboard itself.

### The embed events involved

For filters, the dashboard emits `dashboard:filters` with the full current filter state whenever a user applies one. Your application sends `dashboard:set-filters` into the dashboard's iframe to apply a saved configuration; only the filters included in that payload change, and any filters left out keep their existing values.

> [!NOTE]
>
> `dashboard:set-filters` and the older `dashboard:filter-change-by-url-parameter` are synonyms — they take the same payload and Omni handles them the same way. Use `dashboard:set-filters` in new code.

Controls work the same way, with their own pair of events: `dashboard:controls` reports every control's current state, and `dashboard:set-controls` applies saved control values back onto the dashboard.

> [!NOTE]
>
> `dashboard:filter-changed` and `dashboard:control-changed` are also available if you only need to react to what just changed (for example, to log which filter or control a user just touched) rather than the full state every time.

### Where configurations get stored

`localStorage` is the fastest way to get this working, and it's fine for a single-user, single-device scenario. For anything a user should be able to reach from another device, or that your team needs to manage, store configurations in your own backend instead, keyed to the user and the dashboard.

## Set up two-way messaging

Both directions use the browser's `postMessage` API, so you need a listener for events coming from Omni and a way to post events into the dashboard's iframe.

### Wait for the right readiness event

Before sending anything into the iframe, wait for Omni to say it's listening. `page:ready` fires once the embedded page can receive events at all; `dashboard:ready` fires every time a dashboard finishes loading, including after in-app navigation, and is the event to key off if you want to reapply a saved view each time a dashboard loads.

```typescript theme={null} theme={null}
useEffect(() => {
  const listener = (event: MessageEvent) => {
    if (event.origin !== "https://your-org.embed-omniapp.co") return;

    if (event.data?.name === "dashboard:ready") {
      const { dashboardId } = event.data.payload;
      applySavedViewIfAny(dashboardId);
    }
  };

  // Add the listener before the iframe starts to load
  window.addEventListener("message", listener);
  return () => window.removeEventListener("message", listener);
}, []);
```

Omni queues `dashboard:set-filters` and `dashboard:set-controls` events sent before the dashboard is ready and applies them once it is, so sending slightly early isn't harmful, but waiting for `dashboard:ready` is the documented way to avoid racing the dashboard's own initial-filter event and avoids guessing at a load-complete signal.

### Listen for filter and control changes

Add a `message` listener on the parent window and filter for events from your Omni embed domain:

```typescript theme={null} theme={null}
useEffect(() => {
  const listener = (event: MessageEvent) => {
    // Only accept messages from your known embed origin
    if (event.origin !== "https://your-org.embed-omniapp.co") return;

    if (event.data?.name === "dashboard:filters") {
      setCurrentFilters(event.data.payload);
    }

    if (event.data?.name === "dashboard:controls") {
      setCurrentControls(event.data.payload);
    }
  };

  window.addEventListener("message", listener);
  return () => window.removeEventListener("message", listener);
}, []);
```

Check `event.origin` against your exact embed domain (or vanity domain, if you've set one up) rather than a substring match, so a page on an unrelated domain that happens to contain your domain name as a substring can't get its messages processed.

### Send filters and controls back to the dashboard

Each filter in a `dashboard:filters` payload includes an `asJsonUrlSearchParam` value; each control in a `dashboard:controls` payload includes an `asUrlSearchParam` value (which can be `null` — skip those rather than joining them). Join the ones you want to restore and send them as `dashboard:set-filters` and `dashboard:set-controls` events:

```typescript theme={null} theme={null}
const applyConfig = (config: SavedView) => {
  const filterUrlParameter = Object.values(config.filters ?? {})
    .map((filter: any) => filter.asJsonUrlSearchParam)
    .filter(Boolean)
    .join("&");

  const controlUrlParameters = Object.values(config.controls ?? {})
    .map((control: any) => control.asUrlSearchParam)
    .filter((param): param is string => param !== null);

  const omniOrigin = "https://your-org.embed-omniapp.co";

  if (filterUrlParameter) {
    iframeRef.current?.contentWindow?.postMessage(
      { name: "dashboard:set-filters", payload: { filterUrlParameter } },
      omniOrigin
    );
  }

  if (controlUrlParameters.length > 0) {
    iframeRef.current?.contentWindow?.postMessage(
      { name: "dashboard:set-controls", payload: { controlUrlParameters } },
      omniOrigin
    );
  }
};
```

> [!TIP]
>
> Use your actual embed origin as the target in `postMessage`, not a wildcard (`*`). A wildcard target sends the message to whatever origin the iframe happens to be pointed at, including one an attacker redirected it to.

A child control that follows a parent control reports a `null` `asUrlSearchParam` on purpose — the parent's own parameter reproduces it. Sending an explicit value for that child would win over the parent on replay and stop it from following later parent changes, so leaving it out (which the `filter(Boolean)` above already does) is correct, not an oversight.

## Handle timing and normalization issues

Two dashboards with the same filters and controls applied don't always produce identical payloads, so comparing saved state against current state takes a bit of care.

### Filter out inactive and display-only fields

`dashboard:filters` includes every filter defined on the dashboard, not just the ones a user has actually set, and `dashboard:controls` likewise lists every control, including ones with no URL value. Presence in either payload doesn't mean something is active, so check values before treating an entry as part of the user's configuration: for list filters, check that `values` has at least one entry; for date ranges, check that the range bounds are non-null; for controls, check `value` rather than assuming the key means anything.

The payload can also include display-only properties, such as `appliedLabels` on a filter, that vary between otherwise-identical states. Strip these before comparing two configurations or storing one.

### Compare state reliably

If you want to detect whether a user's current filters match a saved configuration, don't compare the raw strings. Parse each filter's JSON, remove display-only keys, sort the remaining keys, and re-serialize before comparing:

```typescript theme={null} theme={null}
const DISPLAY_ONLY_KEYS = new Set(["appliedLabels"]);

function canonicalize(value: unknown): string {
  if (value && typeof value === "object") {
    const keys = Object.keys(value)
      .filter((key) => !DISPLAY_ONLY_KEYS.has(key))
      .sort();
    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize((value as any)[k])}`).join(",")}}`;
  }
  return JSON.stringify(value);
}
```

## Manage saved configurations

Once capture and restore are working, the rest is standard CRUD against whatever store you chose.

### Update, rename, and duplicate

Update a configuration by replacing its stored filters and controls with the current state; rename or duplicate it by copying the record and changing its name or ID. None of these operations touch the dashboard directly, they only change what you have saved.

### Isolate configurations by user and dashboard

Filter and control specifications are specific to the dashboard they came from and won't produce the intended result if applied to a different one, so key your stored configurations by dashboard ID as well as by user. If configurations are stored client-side, clear them when a user switches dashboards or accounts; if they're stored on your backend, scope queries to the current user and organization.

## Embedded apps

Apps follow a different model, and the dashboard pattern above doesn't carry over directly. An [app](https://docs.omni.co/visualize-present/apps) manages its own query filters internally through `omni.query(name).setFilter()` and `.removeFilter()` calls in the app's own code, and Omni doesn't currently expose an inbound embed event that lets your page set those filters from outside.

What you can do from your embedding page is observe what's happening inside the app and react to it:

```typescript theme={null} theme={null}
window.addEventListener("message", (event) => {
  if (event.origin !== "https://your-org.embed-omniapp.co") return;

  if (event.data?.name === "app:filter-changed") {
    const { filters, changed } = event.data.payload;
    saveAppFilterState(filters);
    console.log("App filter changed:", changed);
  }

  if (event.data?.name === "app:event") {
    const { name, payload } = event.data.payload;
    if (name === "account-selected") {
      showAccountDetail(payload.accountId);
    }
  }
});
```

`app:filter-changed` reports the app's complete filter overrides after each change, keyed by query name and field, plus a `changed` array describing just what's different. `app:event` carries whatever an app's own code chooses to emit with `omni.emit(name, payload)`, which is useful if the app you're embedding was built to broadcast its own selections (a row click, a view toggle) rather than only its query filters.

To actually restore a saved state inside an app, the restoration logic has to live in the app's own code, reading from wherever the app persists its state (an Omni user attribute, a call to your backend, or `omni` SDK storage inside the app) and calling `setFilter()` itself on load. Your embedding page can supply a user attribute, a signed parameter, or data through `app:event` for the app to consume, but it can't force a filter into the app the way `dashboard:set-filters` forces one into a dashboard.

## Known limitations

> [!WARNING]
>
> Omni's embed events don't support clearing all filters or controls on a dashboard programmatically. Sending an empty `filterUrlParameter` or an empty `controlUrlParameters` array won't reset the dashboard to its unfiltered, default-control state.

Work around this by giving users a saved "default" configuration with no filters or non-default controls applied, or by remounting the dashboard iframe (for example, by changing its `key` or re-signing its URL) to force it back to its initial state. Remounting loses the user's scroll position, but it's the most reliable way to get a clean slate.

## Next steps

* Read the [embed events overview](https://docs.omni.co/embed/events.md) for the full list of events Omni can send and receive
* Set up a [vanity domain](https://docs.omni.co/embed/customization/vanity-domains.md) if you haven't already, so your application and the embedded dashboard share a top-level domain
* Reference [filterSearchParam](https://docs.omni.co/embed/setup/url-parameters/filterSearchParam.md) if you'd rather set a user's initial filters at login instead of after the dashboard has loaded
