Modal & Inline Embed

Two presentations built on top of SwapperIframe: a centered modal popup, and an inline embed that reveals a preloaded widget over a placeholder for an instant open. Both live in @swapper-finance/deposit-sdk.

Modal — SwapperModal / openSwapperModal

A modal overlay with a backdrop, CSS animations, escape / click-outside to close, and body-scroll locking.

Quick open

import { openSwapperModal } from "@swapper-finance/deposit-sdk";

const modal = openSwapperModal({
  integratorId: "your-id",
  dstChainId: "8453",
  dstTokenAddr: "0x833…913",
  depositWalletAddress: "0x2A0…28A",
  onClose: () => console.log("Modal closed"),
});

// close programmatically
modal.close();

The class API

For more control, use SwapperModal directly:

import { SwapperModal } from "@swapper-finance/deposit-sdk";

const modal = new SwapperModal({
  integratorId: "your-id",
  dstChainId: "8453",
  dstTokenAddr: "0x833…913",
  depositWalletAddress: "0x2A0…28A",
  onClose: () => console.log("closed"),
});

modal.open();
modal.isModalOpen();      // → boolean
modal.getIframe();        // → underlying SwapperIframe
modal.updateConfig({ /* patch */ });
modal.close();            // hide (widget stays loaded), route back to home
modal.destroy();          // full teardown

close() hides the modal but keeps the widget loaded for an instant reopen, and tells the widget to return to its home screen so the next open() starts fresh rather than resuming the previous selection.

modalStyle

Style the modal chrome (distinct from the widget's own styling):

Field	Default	Description
width	"450px"	Modal width.
height	"560px"	Modal height.
overlayColor	"rgba(0,0,0,0.7)"	Backdrop color.
borderRadius	"30px"	Modal corner radius.
zIndex	10000	Stacking order.

The widget renders its own close button inside the modal (and the modal closes on its close_request), so there is no separate modal-level close-button option — style the button via the widget theme.

Flexible height

The modal auto-enables the widget's flexible home-page height: the home screen scales to its content (instead of the fixed 560px), and the modal smoothly animates to match (clamped to 90% of the viewport). Users with prefers-reduced-motion get an instant snap. Nothing to configure.

Preloading the modal

Build the modal hidden and load the widget in the background so the first open() is instant:

import { preloadSwapperModal } from "@swapper-finance/deposit-sdk";

// when your page mounts
const modal = preloadSwapperModal({
  integratorId: "your-id",
  dstChainId: "8453",
  dstTokenAddr: "0x833…913",
  depositWalletAddress: "0x2A0…28A",
});

// later, on user action — opens instantly
button.addEventListener("click", () => modal.open());

Equivalent to new SwapperModal({ ..., preload: true }) or calling modal.preload().

If something changed between preload and open (say the deposit address), pass a patch to open() — it's applied to the live widget right before it becomes visible:

modal.open({ depositWalletAddress: "0x...newAddress" });

updateConfig(patch) and updateSigner(signer) are also exposed directly and are safe to call before the modal has been built.

Preload loads the widget but holds smart-wallet authorization until the first open().

Inline embed — SwapperEmbed

For widgets that live in the page layout (not a modal) but should still open instantly. The iframe loads immediately on a hidden position: fixed host; showIn(target) moves the host over the target element's box, so the already-loaded widget appears there with no reload.

import { preloadSwapperEmbed } from "@swapper-finance/deposit-sdk";

// when your page mounts — starts loading in the background
const embed = preloadSwapperEmbed({
  integratorId: "your-id",
  dstChainId: "8453",
  dstTokenAddr: "0x833…913",
  depositWalletAddress: "0x2A0…28A",
});

// later — the widget appears over the placeholder instantly
button.addEventListener("click", () => embed.showIn("#widget-placeholder"));

embed.hide();     // widget stays loaded, routes back to home
embed.destroy();  // full teardown

The target is a placeholder: size it to the box the widget should occupy (e.g. 450px × 560px). The host mirrors the target's drawable box — rect, corner radii, border widths, and stacking position — and follows it across scrolling, resizes, and size changes. The iframe is never reparented in the DOM (that would force a reload).

Pass flexibleHeight: true to let the home page auto-scale; the embed animates the placeholder's height so your page layout reflows with it.

Like the modal, smart-wallet authorization is deferred until the first showIn().

Which one?

• A button that pops a dialog → openSwapperModal.

• The same, but instant → preloadSwapperModal.

• A widget that sits in your layout and opens instantly → preloadSwapperEmbed.

• Full manual control over an inline iframe → SwapperIframe.