Choose iframe or popup mode

The App Kit SDK exposes two ways to mount the Onramp widget:

kit.onramp.mountIframe embeds the widget as an inline <iframe> inside a container element you own. Use this when you have room in your layout for a 720+ pixel-tall surface.
kit.onramp.openWindow launches the widget as a separate popup window. Use this when inline embedding does not fit your UX, when iOS Safari’s storage restrictions block the iframe flow, or when you want the widget to feel separate from your app.

Both are synchronous functions. Both return a widget controller you can subscribe to. They differ in where the widget renders and in what can go wrong.

When to pick each mode

Situation	Recommended mode
Default for most apps	`mountIframe`
Page has no space for an inline 720px widget	`openWindow`
Users are on iOS Safari and KYC fails inside the iframe	`openWindow`
App is installed as a PWA in standalone mode	`mountIframe`
You need to launch the widget from a modal or drawer	`mountIframe`

iOS Safari’s Intelligent Tracking Prevention can restrict storage inside a cross-origin iframe, which sometimes breaks the embedded app’s session handling. If you see issues isolated to iOS Safari, use openWindow on that platform.

Iframe mode

mountIframe does not require a user gesture. You can call it on page load, from your framework’s mounted lifecycle, or after any await. The container element must already be attached to the document and must have an explicit, non-zero height:

TypeScript

const widget = kit.onramp.mountIframe({
  session,
  container: document.getElementById("onramp-root")!,
});

See the quickstart for an end-to-end example. openWindow must be called synchronously from a user gesture (a click handler, for example). If you await before calling, the browser blocks the popup because the user-gesture context has expired. Mint the session ahead of time, then call openWindow directly from the click handler:

TypeScript

import { AppKit } from "@circle-fin/app-kit";

const kit = new AppKit();

// Mint the session when the form is rendered, not on click.
const session = await kit.onramp.fetchSession({
  url: "/api/onramp/sessions",
  body: { appUserId, destinationAddress },
});

button.addEventListener("click", () => {
  const result = kit.onramp.openWindow({
    session,
    onDepositSettled: ({ payload }) => console.log("settled", payload),
  });

  if (result.status === "opened") {
    result.widget.on("DEPOSIT_NOT_COMPLETED", ({ code }) => {
      console.log("not completed", code);
    });
  }
});

openWindow returns a discriminated result rather than throwing, so a blocked popup is a normal flow you handle in code, not an exception. When openWindow cannot open a usable popup, it returns { status: 'blocked', reason }. The reason field tells you why, and what to do about it:

`reason`	Cause	Recommended fallback
`popup_blocked`	The browser’s popup blocker rejected the call, or an `await` ran before `openWindow`.	Ask the user to retry from a fresh synchronous click.
`in_app_browser`	The page is running inside an Instagram, Facebook, TikTok, LinkedIn, WeChat, or LINE WebView.	Fall back to `mountIframe`, or prompt the user to open the page in their system browser.
`pwa_standalone`	The page is running inside an installed PWA in standalone display mode.	Fall back to `mountIframe`.

Example with all three fallbacks:

TypeScript

button.addEventListener("click", () => {
  const result = kit.onramp.openWindow({ session, onDepositSettled });

  if (result.status === "blocked") {
    if (result.reason === "popup_blocked") {
      showPopupRetryDialog(result.errorMessage);
    } else {
      kit.onramp.mountIframe({ session, container });
    }
    return;
  }

  result.widget.on("DEPOSIT_NOT_COMPLETED", handleNotCompleted);
});

On mobile browsers, window.open opens a new tab rather than a sized popup. The width and height features are ignored. Design your UX for both outcomes. If the user closes the popup before submitting a deposit, the App Kit SDK detects it and synthesizes a DEPOSIT_NOT_COMPLETED event with code CANCELED_BY_CUSTOMER. Your onDepositNotCompleted handler runs without any extra polling on your side. Both mountIframe and openWindow return a controller with a close() method. Call it when the user leaves the view, closes the modal, or starts over:

TypeScript

let widget: { close: () => void } | undefined;

function mountCurrentSession() {
  widget?.close();
  widget = kit.onramp.mountIframe({ session, container });
}

function stopOnramp() {
  widget?.close();
  widget = undefined;
}

For iframe mode, the kit auto-disposes the widget if the container is removed from the DOM without a close() call. Call widget.close() when you know the widget is no longer needed.

Send

Bridge

Swap

Unified Balance

Onramp

Earn

Choose iframe or popup mode

When to pick each mode

Iframe mode

Close the widget

​When to pick each mode

​Iframe mode

​Popup mode

​Handle a blocked popup

​Popup behavior on mobile

​Popup closed before deposit

​Close the widget

When to pick each mode

Iframe mode

Popup mode

Handle a blocked popup

Popup behavior on mobile

Popup closed before deposit

Close the widget