@salesforce/sdk-view

View SDK for displaying notifications, modals, and managing visual state across Salesforce application surfaces. Provides a unified API for alerts, toasts, modal dialogs, theming, and viewport resizing — automatically adapting to the host environment.

Installation

npm install @salesforce/sdk-view

Quick Start

import { createViewSDK } from "@salesforce/sdk-view";

const sdk = await createViewSDK();

// Show a success toast
await sdk.displayToast?.({ message: "Record saved", level: "success" });

// Check the host theme
const theme = sdk.getTheme?.();
if (theme?.mode === "dark") {
  document.body.classList.add("dark");
}

Initialization

Factory (Async)

createViewSDK detects the runtime surface and returns the appropriate implementation. Each call creates a new instance.

const sdk = await createViewSDK();

Singleton (Recommended)

getViewSDK caches the instance so all callers share one SDK. The Promise itself is cached, preventing race conditions from concurrent callers.

import { getViewSDK } from "@salesforce/sdk-view";

const sdk = await getViewSDK();

Synchronous Access

After getViewSDK() has resolved, you can access the instance synchronously. Returns null if not yet initialized.

import { getViewSDKSync } from "@salesforce/sdk-view";

const sdk = getViewSDKSync(); // ViewSDK | null

Options

import { Surface } from "@salesforce/sdk-core";

const sdk = await createViewSDK({
  // Force a specific surface (skip auto-detection)
  surface: Surface.MCPApps,
  // MCP Apps session options
  mcpApps: {
    appIdentity: { name: "my-app" },
    handshakeTimeout: 5000,
  },
});

Reset (Testing)

import { resetViewSDK } from "@salesforce/sdk-view";

resetViewSDK(); // Clears cached singleton; next getViewSDK() creates fresh instance

API Reference

All ViewSDK methods are optional — availability depends on the runtime surface. Always use optional chaining (?.) when calling them.

displayAlert

Display a modal notification that requires user acknowledgment.

await sdk.displayAlert?.({
  message: "Please save your work before continuing",
  level: "warning",
});

| Param | Type | Default | Description | | --------- | -------------- | -------- | ------------------------------------------------------------- | | message | string | — | Message text to display | | level | MessageLevel | "info" | Severity: "info" | "success" | "warning" | "error" |

displayToast

Display a non-blocking notification that auto-dismisses.

await sdk.displayToast?.({
  message: "File uploaded successfully",
  level: "success",
});

Same parameters as displayAlert.

displayModal

Display a custom HTML dialog. OpenAI surface only (MCP Apps not yet implemented).

await sdk.displayModal?.({
  componentReference: "ui://widget/settings.html",
  params: { userId: "123", mode: "edit" },
});

| Param | Type | Description | | -------------------- | ------------------------- | ------------------------------------------------------ | | componentReference | string | URI of the HTML template ("ui://widget/[name].html") | | params | Record<string, unknown> | Optional parameters passed to the modal |

On OpenAI, params are accessible in the modal via window.openai.view.params.

getTheme

Get the current theme mode from the host.

const theme = sdk.getTheme?.();
if (theme) {
  console.log(theme.mode); // "light" | "dark"
}

Returns Theme | null. The Theme type is { mode: ThemeMode } where ThemeMode = "light" | "dark".

resize

Resize the widget viewport. MCP Apps only. Accepts pixel values as strings.

await sdk.resize?.("800px", "600px");
await sdk.resize?.("1024", "768"); // unitless = pixels

| Param | Type | Description | | -------- | -------- | -------------------------------------------------------------- | | width | string | Width in pixels ("800px" or "800"). Empty string to omit. | | height | string | Height in pixels ("600px" or "600"). Empty string to omit. |

Only pixel values are accepted. Percentages, rem, em, vw/vh, auto, and negative values are rejected.

navigateTo

Navigate to a URL within the host environment.

await sdk.navigateTo?.("/dashboard");

markDirtyState / clearDirtyState

Notify the host about unsaved changes. The host may show a visual indicator or prompt before closing.

// User edited a form
await sdk.markDirtyState?.();

// After saving
await sdk.clearDirtyState?.();

dispatchEvent

Send a custom event with data to the host.

await sdk.dispatchEvent?.("user-action", {
  action: "click",
  buttonId: "submit",
});

getUiProps

Get host-provided UI properties and subscribe to changes.

const uiProps = sdk.getUiProps?.();

const initialProps = await uiProps.props;
uiProps.subscribe((newProps) => {
  // Update UI based on new props
});

Surface Capabilities

Not all methods are available on every surface. Use getSurfaceCapabilities from @salesforce/sdk-core to check at runtime, or refer to this matrix:

| Method | MCP Apps | OpenAI | Salesforce ACC | | -------------- | -------- | ------ | -------------- | | displayAlert | Yes | Yes | Yes | | displayToast | Yes | Yes | Yes | | displayModal | No | Yes | No | | getTheme | Yes | Yes | Yes | | resize | Yes | No | No |

WebApp and Mosaic surfaces return an empty object with no methods.

import { getSurface, getSurfaceCapabilities } from "@salesforce/sdk-core";

const caps = getSurfaceCapabilities(getSurface());
if (caps.resize) {
  await sdk.resize?.("800px", "600px");
}

Exported Types

import type {
  ViewSDK,
  AlertOptions,
  ToastOptions,
  ModalOptions,
  Theme,
  ThemeMode,
  SDKOptions,
} from "@salesforce/sdk-view";

import type { ViewSDKOptions } from "@salesforce/sdk-view";

Architecture

The View SDK is part of the Salesforce Platform SDK ecosystem:

• @salesforce/sdk-core — Surface detection, McpAppsSession singleton, shared interfaces
• @salesforce/sdk-chat — Conversational flow participation (messages, tools, resources)
• @salesforce/sdk-view — Visual interactions (notifications, modals, theming, resize)

Both sdk-chat and sdk-view share a single McpAppsSession transport when running on MCP Apps, so the SEP-1865 handshake only happens once regardless of initialization order.

License

Copyright (c) 2026, Salesforce, Inc. All rights reserved. For full license text, see the LICENSE.txt file.