Warn Users About Unsaved Changes in an Embedded App (Developer Preview)

Protect users from losing unsaved work by telling Salesforce when your embedded app has unsaved changes. When the app is dirty and the user tries to navigate away, Salesforce shows a confirmation prompt.

This topic describes the Developer Preview API. Your app registers dirty state by dispatching a trackdirtystate event on the bridge, using the public bridge.instanceId value to identify the widget. In the generally available release, instanceId is no longer public and dirty state is registered through an SDK method instead, so this exact pattern doesn’t carry forward. To move an app to the generally available version, see Migrate from the Developer Preview API.

Note

How It Works

Your embedded app tells the host when it becomes dirty or clean by dispatching a trackdirtystate event on the bridge. The shell forwards that event to the host platform. When a dirty app is registered and the user navigates away, the platform shows a single confirmation modal with cancel and discard options. If several embedded apps are dirty at once, the platform still shows one modal for all of them.

Report Dirty State

When your app’s state changes, dispatch a trackdirtystate event on the bridge. Guard the call with bridge.isConnected() so you only dispatch after the connection is ready.

1if (bridge.isConnected()) {
2  bridge.dispatchEvent(
3    new CustomEvent("trackdirtystate", {
4      detail: {
5        isDirty: true,
6        instanceId: bridge.instanceId,
7        label: "Registration form",
8      },
9    }),
10  );
11}

isDirty: true when the app has unsaved changes, false when it’s clean.
instanceId: identifies the embedded app instance. Read it from bridge.instanceId.
label: an optional, human-readable name for the app. The platform can show it in the confirmation modal so users know which app has unsaved work.

Dispatch the event again with isDirty: false when the user saves or the app returns to a clean state.

Where It Works

Dirty-state protection works on Lightning Experience pages and on Experience Cloud sites, including both LWR-based and Aura-based sites.

Known Limitations