Make Your Embedded App Work with the Host Page
Learning Objectives
After completing this unit, you’ll be able to:
- Set up the View SDK in your embedded app.
- Describe how your app receives styling values from the host page.
- Warn users about unsaved changes before they leave the page.
- Explain how the iframe sizes to fit your app.
Make Your App Feel at Home
In the previous unit, you embedded your app, and it renders on the page. Your app already works there. It reads and writes records through Data SDK the same way it does on its own, so you don’t change any data code to embed it.
To make the app feel like part of the page, use the View SDK. The View SDK comes from @salesforce/platform-sdk, the same package that provides Data SDK. Where Data SDK handles your app’s data, the View SDK handles how your app fits into the page that hosts it. Multi-Framework app templates include this package, so there’s nothing new to install.
Set Up the View SDK
The UI Embedding import that you added to your app’s entry point connects your app to the host page and starts automatic resizing. The View SDK uses the same connection.
Now create the View SDK where you need it. createViewSDK() is asynchronous. When your app isn’t embedded, such as when a user opens it from the App Launcher, createViewSDK() resolves to an empty object rather than failing. Every method on the SDK is optional, so guard each call with optional chaining (?.). That way, the same app code works both embedded and on its own.
import { createViewSDK } from "@salesforce/platform-sdk/view";
const viewSdk = await createViewSDK();Match the Host Page’s Styling
Your app runs in its own iframe, so the host page’s styles don’t reach it. Instead, the host decides which values to share. In the wrapper component, set CSS custom properties inline on the lightning-ui-embedding element. Your app reads them from state.styles.variables in getUiState() and applies them. It also subscribes to changes, so it can reapply the values when the host updates them.
const uiState = viewSdk.getUiState?.();
if (uiState) {
applyStyles(uiState.state.styles?.variables);
uiState.subscribe((next) => applyStyles(next.styles?.variables));
}In this example, applyStyles() is your own function. Each variable arrives with its full name, such as --brand-color, so your app can set it directly on its root element. The app also receives HTML attributes, such as dir and lang, in state.styles.attributes. For the full pattern, see Style an Embedded App to Match Salesforce.
Warn About Unsaved Changes
If your app has unsaved work, let the host warn users before they leave the page. For example, say a property management app has a form for editing a property’s details. Mark the app dirty when the form has unsaved changes and clear the dirty state after the save succeeds. The optional label lets you track more than one dirty region at a time.
await viewSdk.markDirtyState?.("propertyForm");
// ...after a successful save:
await viewSdk.clearDirtyState?.("propertyForm");Fit the Iframe to Your App’s Content
Your app reports its height to the host, and the host sizes the iframe to match. Reporting starts automatically when your app imports @salesforce/platform-sdk/ui-embedding, so keep that import at your entry point. To set a size yourself, call viewSdk.resize?.(width, height) with pixel strings. Pass an empty string for an axis that you don’t want to change. For example, await viewSdk.resize?.("", "640px") sets the height to 640 pixels and leaves the width as is.
Avoid full-viewport heights, such as height: 100vh, in your app. Inside the iframe, 100vh is the iframe’s own height, so your app can’t grow to fit its content.
Keep Building
You started this badge with a Multi-Framework app that users open from the App Launcher. Now you know how to embed your app on a Lightning Experience page or an Experience Cloud site page, match the host page’s styling, and warn users about unsaved changes. Build the app once, and it can show up wherever your users work.
As you keep building, try embedding your app on other pages or embedding another Multi-Framework app built with React or Angular.