One iframe, no backend.

This is the widget, live#

Not a screenshot — the frame below is a real /embed instance, loaded the same way your visitors would load it. It quotes and signs for real, so treat anything you do inside it as production.

Two ways in, and why there are two#

The builder has a Simple tab and an Advanced tab, and the difference is not how much you are allowed to change — it is how the change travels.

Styling used to go entirely through the query string, which capped the depth of customisation at how much fits in a URL: a theme, an accent, a radius. The ceiling was never the iframe. postMessage carries a structured object of any size, so a full palette, a font stack and two radius levels are available without extracting the application into a React component. Simple is the query string; Advanced is the object.

The simple snippet#

<iframe id="swapspro"
  src="https://www.swaps.pro/embed?theme=dark&accent=%234DF98A&radius=16&width=440"
  width="440" height="640"
  style="border:0;border-radius:16px;display:block;max-width:100%"
  title="SwapsPro widget" allow="clipboard-write"></iframe>
<script>
  // Height is reported, not guessed. This is what removes the scrollbar.
  addEventListener("message", function (e) {
    if (e.source !== document.getElementById("swapspro").contentWindow) return;
    if (e.data && e.data.type === "swapspro:height")
      document.getElementById("swapspro").style.height = e.data.height + "px";
  });
</script>

One iframe and eight lines of script. No npm package, no API key, no backend. The iframe target is /embed — a stripped swap card with no site navigation, deliberately kept out of the sitemap and disallowed in robots.txt so it can never outrank the app itself in search.

Height is measured, not guessed#

The widget measures itself with a ResizeObserver and posts its height to the parent:

{ type: "swapspro:height", height: 612 }

• Why it exists. A fixed iframe height is a guess about content whose height changes — a quote arriving, a recipient field appearing on a cross-chain pair, an error line wrapping. Guess low and the visitor gets a scrollbar over somebody else’s page; guess high and there is dead space under the card. The embed also used to set minHeight: 100dvh, which inside a fixed-height frame guarantees the scrollbar.
• Listening is optional. Without the listener the message is inert and the frame keeps whatever height you set, so an embed written before this existed cannot break.
• It only posts on real change — under two pixels is ignored, so an animation cannot make the parent do layout every frame.
• Check the source. The example listener compares e.source against the frame’s contentWindow; any page can post a message at yours.

In React, there is a component that does both halves#

@swapspro/widget wraps the same iframe and installs the two pieces you would otherwise write yourself: the height listener, and the theme push on load and on every change. It is a wrapper, not a port — the swap card still runs in the frame, deployed by us, because shipping quoting, routing, wallet handling and fee collection into somebody else’s bundle means shipping every future bug in them into a page whose owner cannot patch it.

import { SwapProWidget } from "@swapspro/widget";

// The minimum is one prop, and even that is optional.
<SwapProWidget accent="#4DF98A" />;

// The same theme object the postMessage path takes, as a prop. Changing it
// re-posts rather than remounting, so a typed amount and a live quote survive.
<SwapProWidget
  appearance="light"
  chrome="bare"
  sell="base-eth"
  buy="base-usdc"
  theme={{
    colors: { canvas: "#FFFFFF", surface: "#FFFFFF", text: "#101418", accent: "#3B82F6" },
    fontFamily: '"Inter", system-ui, sans-serif',
    shape: { borderRadius: 20, borderRadiusSecondary: 8 },
  }}
  onHeightChange={(h) => console.log("card is", h, "px tall")}
/>;

Query parameters#

Two groups, honoured by two different layers. The first are the embed's own styling; the rest are the swap card's deep-link parameters, which work on /swap too. Note that tab is not among them — the tab bar lives on /swap, not inside the frame.

Styling#

Pre-filling the swap#

<!-- Land on a specific pair with an amount pre-filled.
     Slugs are chain-symbol, lowercase: eth-usdc, base-weth, btc-btc, hive-hbd. -->
<iframe
  src="https://www.swaps.pro/embed?theme=dark&sell=base-eth&buy=base-usdc&amount=0.1"
  width="440" height="640" style="border:0" title="SwapsPro widget"
></iframe>

The Advanced theme object#

Post { type: "swapspro:style", theme: {...} } at the frame and the widget restyles in place. Every key maps to a CSS variable the app already renders through — a smaller surface than arbitrary per-component overrides, and an honest one: every key below does something.

<iframe id="swapspro" src="https://www.swaps.pro/embed?theme=dark&chrome=none"
  width="440" height="640"
  style="border:0;border-radius:16px;display:block;max-width:100%"
  title="SwapsPro widget" allow="clipboard-write"></iframe>
<script>
  var f = document.getElementById("swapspro");
  var theme = {
    colors: {
      canvas: "#0b0f0d",
      surface: "rgb(17, 24, 20)",
      surfaceSunken: "#0e1411",
      borderSubtle: "#1e2a24",
      text: "#e8f1ec",
      textMuted: "#9fb3a8",
      accent: "#4DF98A",
      accentText: "#04120a",
      accentSoft: "#4DF98A1f"
    },
    fontFamily: '"Inter", system-ui, sans-serif',
    shape: { borderRadius: 20, borderRadiusSecondary: 10 }
  };

  // Push it once the frame has a document, and again any time you change it.
  function style() {
    f.contentWindow.postMessage({ type: "swapspro:style", theme: theme }, "*");
  }
  f.addEventListener("load", style);

  addEventListener("message", function (e) {
    if (e.source !== f.contentWindow) return;
    if (e.data && e.data.type === "swapspro:height") f.style.height = e.data.height + "px";
  });
</script>

The 12 colour keys, in the order you would reason about them — the surfaces first, then what sits on them, then the accent: canvas, surface, surfaceRaised, surfaceSunken, borderSubtle, borderStrong, text, textMuted, textSubtle, accent, accentText, accentSoft.

• Send only the keys you set. An empty object means “use the widget’s own palette”.
• theme: null clears it. An absent theme key leaves the current one alone, so a host can update the simple style and the deep theme independently in one message.
• The variables are removed by exactly the keys that were set — never a blanket reset, which would take the app’s own variables with it.
• The style half of the message is validated identically to the URL. Both are untrusted input and neither gets to set a value we would not accept from the other.

Removing the badge is a Pro benefit, and it is proved#

A small ⚡ swaps.pro link sits in the bottom-right of the frame. Passing brand=0 with pro=<address> removes it — but only after the pass is read on chain, with the same tokenOf call on Base (chain 8453) the app uses for its own Pro check.

It fails closed. Until the read comes back positive the badge renders, so a network problem, an RPC outage or a made-up address all end with the attribution still on the page. The opposite design — hide first, restore if the check fails — hands the benefit to exactly the population that would arrange for the check not to complete.

Sizing#

• Width. The card is capped by width (default 480, max 720) and centres itself in whatever box you give it, so a wider iframe just adds empty space either side. Below about 320px the amount row starts to crowd.
• Height. Set a sensible starting value — the builder emits 640 — and let the height message correct it on first paint. That is the whole sizing story now.
• Responsive. width: 100% on the iframe with a max-width on a wrapper, and the height listener installed. Nothing else is needed.

Widget or SDK?#

The widget is the whole SwapsPro experience in a box: you get everything, and you restyle it. The SDK is the opposite trade.

What the widget still cannot do#

• No partner id. The embed honours no attribution parameter, so an embed cannot be credited to you. If revenue share matters, use the SDK.
• No flow events. The only message the frame emits is its height. The parent cannot observe a connect, a quote or a completed swap.
• No control over the swap after load. Style is live; the pair and the amount are not. To change those, change the iframe's src.
• No custom token list. The selector is SwapsPro's.
• No per-component style overrides. The theme reaches CSS variables the app already renders through, and nothing beyond them.
• Instant swaps only. The frame renders the swap card without the tab bar, so limit orders and TWAP ladders are not reachable from an embed. Link visitors to /swap for those.

Wallets, fees and behaviour#

Identical to swaps.pro itself. Visitors connect their own browser extension or mobile wallet inside the frame; quotes come from the same routing; the fee is the same fee, and it is on the fees page like everything else. Nothing about being embedded changes the price.

Build one#

The widget builder has both tabs, a live preview on a checkerboard so you can see what is and is not painted, and a copy button on the finished snippet. It is the fastest way to land on values you like before pasting anything into your own page.