From f344fb5fbd553881b5f4ec5dbc7f6de879f7e1ca Mon Sep 17 00:00:00 2001
From: MananTank <manantankm@gmail.com>
Date: Mon, 5 Jan 2026 21:40:36 +0000
Subject: [PATCH] [MNY-351] Portal: Add swap widget iframe docs (#8604)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

<!--

## title your PR with this format: "[SDK/Dashboard/Portal] Feature/Fix: Concise title for the changes"

If you did not copy the branch name from Linear, paste the issue tag here (format is TEAM-0000):

## Notes for the reviewer

Anything important to call out? Be sure to also clarify these in your comments.

## How to test

Unit tests, playground, etc.

-->

<!-- start pr-codex -->

---

## PR-Codex overview
This PR enhances the `Swap Widget` functionality by adding an `iframe` integration option and a new `React Component`. It updates documentation and examples for better usability and expands features like dark/light mode support and customizable token selections.

### Detailed summary
- Added `links` for `React Component` and `Iframe` in `sidebar.tsx`.
- Introduced `IframeCodePreview` component in `iframe-code-preview.tsx`.
- Updated `page.mdx` for `iframe` integration with features and examples.
- Revised `page.mdx` for `react` with improved descriptions and features.
- Enhanced API reference and examples for token selection configurations.
- Added iframe event listening instructions for swap results.

> ✨ Ask PR-Codex anything about this PR by commenting with `/codex {your question}`

<!-- end pr-codex -->
---
 apps/portal/src/app/bridge/sidebar.tsx        |  10 ++
 .../iframe/iframe-code-preview.tsx            |  34 ++++
 .../app/bridge/swap-widget/iframe/page.mdx    | 168 ++++++++++++++++++
 .../src/app/bridge/swap-widget/page.mdx       | 133 +++-----------
 .../src/app/bridge/swap-widget/react/page.mdx | 155 ++++++++++++++++
 5 files changed, 389 insertions(+), 111 deletions(-)
 create mode 100644 apps/portal/src/app/bridge/swap-widget/iframe/iframe-code-preview.tsx
 create mode 100644 apps/portal/src/app/bridge/swap-widget/iframe/page.mdx
 create mode 100644 apps/portal/src/app/bridge/swap-widget/react/page.mdx

diff --git a/apps/portal/src/app/bridge/sidebar.tsx b/apps/portal/src/app/bridge/sidebar.tsx
index 37e4fb4e929..f26740aed07 100644
--- a/apps/portal/src/app/bridge/sidebar.tsx
+++ b/apps/portal/src/app/bridge/sidebar.tsx
@@ -57,6 +57,16 @@ export const sidebar: SideBar = {
         {
           name: "Swap Widget",
           href: `${bridgeSlug}/swap-widget`,
+          links: [
+            {
+              href: `${bridgeSlug}/swap-widget/react`,
+              name: "React Component",
+            },
+            {
+              href: `${bridgeSlug}/swap-widget/iframe`,
+              name: "Iframe",
+            },
+          ],
         },
       ],
     },
diff --git a/apps/portal/src/app/bridge/swap-widget/iframe/iframe-code-preview.tsx b/apps/portal/src/app/bridge/swap-widget/iframe/iframe-code-preview.tsx
new file mode 100644
index 00000000000..dfc87958968
--- /dev/null
+++ b/apps/portal/src/app/bridge/swap-widget/iframe/iframe-code-preview.tsx
@@ -0,0 +1,34 @@
+import { CodeBlock, Tabs, TabsContent, TabsList, TabsTrigger } from "@doc";
+
+export function IframeCodePreview(props: { src: string }) {
+  return (
+    <Tabs defaultValue="code">
+      <TabsList>
+        <TabsTrigger value="code">Code</TabsTrigger>
+        <TabsTrigger value="preview">Preview</TabsTrigger>
+      </TabsList>
+      <TabsContent value="code">
+        <CodeBlock
+          code={`\
+<iframe
+  src="${props.src}"
+  height="750px"
+  width="100%"
+  style="border: 0;"
+/>`}
+          lang="html"
+        />
+      </TabsContent>
+      <TabsContent value="preview">
+        <iframe
+          title="Swap widget iframe"
+          src={props.src}
+          height="750px"
+          className="rounded-xl"
+          width="100%"
+          style={{ border: 0 }}
+        />
+      </TabsContent>
+    </Tabs>
+  );
+}
diff --git a/apps/portal/src/app/bridge/swap-widget/iframe/page.mdx b/apps/portal/src/app/bridge/swap-widget/iframe/page.mdx
new file mode 100644
index 00000000000..9a5f6caab62
--- /dev/null
+++ b/apps/portal/src/app/bridge/swap-widget/iframe/page.mdx
@@ -0,0 +1,168 @@
+import {
+  ArticleIconCard,
+  Details,
+  createMetadata,
+  DocImage,
+} from "@doc";
+import { IframeCodePreview } from "./iframe-code-preview";
+import { PlayIcon } from "lucide-react";
+import SwapWidgetDark from "../../swap/swap-dark.jpg";
+import SwapWidgetLight from "../../swap/swap-light.jpg";
+
+export const metadata = createMetadata({
+  image: {
+    title: "Swap widget iframe",
+    icon: "payments",
+  },
+  title: "Swap widget iframe",
+  description: "Add a widget to swap tokens across chains using an iframe",
+});
+
+# Swap widget iframe
+
+The Swap widget iframe makes it easy to add cross-chain token swaps to your app. Just add an iframe to your HTML and get a fully customizable swap widget - no build setup required.
+
+<div className='dark-only'>
+<DocImage src={SwapWidgetDark} />
+</div>
+<div className='light-only'>
+<DocImage src={SwapWidgetLight} />
+</div>
+
+## Features
+
+- Cross-chain token swaps across 90+ blockchains
+- Route optimization to find the best path for any token pair
+- Dark and light mode support
+- Display fiat values in multiple currencies
+
+## Iframe Integration
+
+The swap widget supports various query parameters to customize the default token selection. All parameters are optional - if not set, the widget will display without any pre-selected tokens.
+
+### Example
+
+
+<IframeCodePreview src="https://thirdweb.com/bridge/swap-widget" />
+
+## Try it out
+
+<ArticleIconCard
+	title="Swap Widget Playground"
+	description="Try out the Swap Widget in our live playground"
+	icon={PlayIcon}
+	href="https://playground.thirdweb.com/bridge/swap-widget?tab=iframe"
+/>
+
+## Options
+
+You can customize the swap widget using query parameters as mentioned below.
+
+### Token Selection
+
+You can prefill the buy and sell token selections using the following parameters:
+
+| Parameter | Description |
+|-----------|-------------|
+| `buyChain` | Chain ID for the buy token (e.g., 1 for Ethereum, 8453 for Base) |
+| `buyTokenAddress` | Token contract address for the buy token. If not set, native token is used |
+| `buyAmount` | Default amount to buy |
+| `sellChain` | Chain ID for the sell token |
+| `sellTokenAddress` | Token contract address for the sell token. If not set, native token is used |
+| `sellAmount` | Default amount to sell |
+
+<Details summary="Set sell token to Base USDC">
+
+<IframeCodePreview src="https://thirdweb.com/bridge/swap-widget?sellChain=8453&sellTokenAddress=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" />
+
+</Details>
+
+<Details summary="Set buy token to Ethereum native (ETH)">
+
+<IframeCodePreview src="https://thirdweb.com/bridge/swap-widget?buyChain=1" />
+
+</Details>
+
+<Details summary="Set both buy and sell tokens">
+
+<IframeCodePreview src="https://thirdweb.com/bridge/swap-widget?sellChain=8453&sellTokenAddress=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913&buyChain=137" />
+
+</Details>
+
+### Theme
+
+By default the widget uses the "dark" theme. You can set the light theme by passing the `theme=light` query parameter.
+
+<IframeCodePreview src="https://thirdweb.com/bridge/swap-widget?theme=light&sellChain=8453" />
+
+
+### Currency
+
+By default the fiat value of the token amounts is displayed in USD. You can change the currency by setting the `currency` query parameter.
+
+<Details summary="Supported Currencies">
+
+- `USD` - US Dollar (default)
+- `EUR` - Euro
+- `GBP` - British Pound
+- `JPY` - Japanese Yen
+- `KRW` - Korean Won
+- `CNY` - Chinese Yuan
+- `INR` - Indian Rupee
+- `NOK` - Norwegian Krone
+- `SEK` - Swedish Krona
+- `CHF` - Swiss Franc
+- `AUD` - Australian Dollar
+- `CAD` - Canadian Dollar
+- `NZD` - New Zealand Dollar
+- `MXN` - Mexican Peso
+- `BRL` - Brazilian Real
+- `CLP` - Chilean Peso
+- `CZK` - Czech Koruna
+- `DKK` - Danish Krone
+- `HKD` - Hong Kong Dollar
+- `HUF` - Hungarian Forint
+- `IDR` - Indonesian Rupiah
+- `ILS` - Israeli New Sheqel
+- `ISK` - Icelandic Krona
+
+</Details>
+
+#### Example
+
+Show fiat values in Euro (EUR) in the widget.
+
+<IframeCodePreview src="https://thirdweb.com/bridge/swap-widget?sellChain=8453&currency=EUR" />
+
+### thirdweb branding
+
+By default, the widget displays thirdweb branding at the bottom. You can hide this by setting the `showThirdwebBranding` query parameter to `false`.
+
+<IframeCodePreview src="https://thirdweb.com/bridge/swap-widget?sellChain=8453&showThirdwebBranding=false" />
+
+## Listening for Events
+
+The swap widget iframe sends events to the parent window using `postMessage` when a swap succeeds or fails.
+
+You can listen for these events to handle the swap result in your application.
+
+```js
+window.addEventListener("message", (event) => {
+
+  // verify that message is from thirdweb swap widget iframe
+  if (
+    event.origin === "https://thirdweb.com" && event.data.source === "swap-widget"
+  ) {
+
+  if (event.data.type === "success") {
+    console.log("Swap successful!");
+  }
+
+  if (event.data.type === "error") {
+    console.error("Swap failed with error:", event.data.message);
+  }
+  }
+
+});
+```
+
diff --git a/apps/portal/src/app/bridge/swap-widget/page.mdx b/apps/portal/src/app/bridge/swap-widget/page.mdx
index f14ccc3711a..d27e51a9930 100644
--- a/apps/portal/src/app/bridge/swap-widget/page.mdx
+++ b/apps/portal/src/app/bridge/swap-widget/page.mdx
@@ -3,7 +3,7 @@ import {
   createMetadata,
   DocImage,
 } from "@doc";
-import { PlayIcon } from "lucide-react";
+import { FrameIcon, PlayIcon } from "lucide-react";
 import { ReactIcon } from "@/icons";
 import SwapWidgetDark from "../swap/swap-dark.jpg";
 import SwapWidgetLight from "../swap/swap-light.jpg";
@@ -19,7 +19,7 @@ export const metadata = createMetadata({
 
 # Swap widget
 
-The Swap widget makes it easy to add cross-chain token swaps to your app using the thirdweb SDK.
+The Swap widget makes it easy to add cross-chain token swaps to your app. It supports swaps across 90+ blockchains with real-time quotes and route optimization to find the best path for any token pair.
 
 <div className='dark-only'>
 <DocImage src={SwapWidgetDark} />
@@ -30,128 +30,39 @@ The Swap widget makes it easy to add cross-chain token swaps to your app using t
 
 ## Features
 
-- Cross-chain token swaps across 50+ blockchains
-- Real-time quotes with up-to-date pricing
+- Cross-chain token swaps across 90+ blockchains
 - Route optimization to find the best path for any token pair
-- Customizable UI - use prebuilt themes or override with your brand colors
+- Customizable UI with dark and light mode support
 - Prefill token selections for a smoother user experience
-- Event callbacks to track user actions (success, error, cancel)
+- Display fiat values in multiple currencies
 
-## Example
+## Get Started
 
-You will need a thirdweb project client id to use the `SwapWidget` component. You can get your clientId by creating a project in the [thirdweb dashboard](https://thirdweb.com/team).
+You can integrate the swap widget into your website using an iframe or a React component.
 
-```tsx
-import { SwapWidget } from "thirdweb/react";
-import { createThirdwebClient } from "thirdweb";
+<div className="space-y-4">
 
-const client = createThirdwebClient({
-  clientId: "YOUR_THIRDWEB_CLIENT_ID",
-});
-
-function Example() {
-  return <SwapWidget client={client} />;
-}
-```
-
-Make sure to wrap the component containing `SwapWidget` with the `ThirdwebProvider` component.
-
-```tsx
-import { ThirdwebProvider } from "thirdweb/react";
-
-function App() {
-  return (
-    <ThirdwebProvider>
-      <YourApp />
-    </ThirdwebProvider>
-  );
-}
-```
-
-## Configuring Default Token Selection
-
-By default, no tokens are selected in the widget UI. You can configure the default token selection by passing in the `prefill` prop. It only sets the default token selection - users can change these selections in the widget UI.
-
-### Set an ERC20 token to Buy by default
-
-```tsx
-<SwapWidget
-  client={client}
-  prefill={{
-    buyToken: {
-      // Base USDC
-      chainId: 8453,
-      tokenAddress: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
-    },
-  }}
-/>
-```
-
-### Set a native token to Sell by default
-
-To configure a native token to sell by default, you can omit the `tokenAddress` property.
-
-```tsx
-<SwapWidget
-  client={client}
-  prefill={{
-    // Base native token (ETH)
-    sellToken: {
-      chainId: 8453,
-    },
-  }}
-/>
-```
-
-### Set amount and token to Buy by default
-
-```tsx
-<SwapWidget
-  client={client}
-  prefill={{
-    buyToken: {
-      chainId: 8453,
-      amount: "0.1",
-      tokenAddress: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
-    },
-  }}
-/>
-```
-
-### Set both buy and sell tokens by default
-
-```tsx
-<SwapWidget
-  client={client}
-  prefill={{
-    // Base USDC
-    buyToken: {
-      chainId: 8453,
-      tokenAddress: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
-    },
-    // Polygon native token (POL)
-    sellToken: {
-      chainId: 137,
-    },
-  }}
+<ArticleIconCard
+	title="Iframe"
+  icon={FrameIcon}
+	description="Integrate swap widget into your website using an iframe"
+	href="/bridge/swap-widget/iframe"
 />
-```
-
-## API Reference
 
 <ArticleIconCard
-  title="SwapWidget Component"
-  description="View the API reference for the SwapWidget component"
+	title="React Component"
   icon={ReactIcon}
-  href="/references/typescript/v5/SwapWidget"
+	description="Integrate swap widget into your app using a React component"
+	href="/bridge/swap-widget/react"
 />
 
+</div>
+
 ## Try it out
 
 <ArticleIconCard
-  title="Swap Widget Playground"
-  description="Try out the Swap Widget in our live playground"
-  icon={PlayIcon}
-  href="https://playground.thirdweb.com/bridge/swap-widget"
+	title="Swap Widget Playground"
+	description="Try out the Swap Widget in our live playground"
+	icon={PlayIcon}
+	href="https://playground.thirdweb.com/bridge/swap-widget"
 />
-
diff --git a/apps/portal/src/app/bridge/swap-widget/react/page.mdx b/apps/portal/src/app/bridge/swap-widget/react/page.mdx
new file mode 100644
index 00000000000..c40681f6bc8
--- /dev/null
+++ b/apps/portal/src/app/bridge/swap-widget/react/page.mdx
@@ -0,0 +1,155 @@
+import {
+  ArticleIconCard,
+  createMetadata,
+  DocImage,
+} from "@doc";
+import { PlayIcon } from "lucide-react";
+import { ReactIcon } from "@/icons";
+import SwapWidgetDark from "../../swap/swap-dark.jpg";
+import SwapWidgetLight from "../../swap/swap-light.jpg";
+
+export const metadata = createMetadata({
+  image: {
+    title: "Swap widget component",
+    icon: "payments",
+  },
+  title: "Swap widget component",
+  description: "Add a widget to swap tokens across chains using a React component",
+});
+
+# Swap widget component
+
+The Swap widget component makes it easy to add cross-chain token swaps to your app
+
+<div className='dark-only'>
+<DocImage src={SwapWidgetDark} />
+</div>
+<div className='light-only'>
+<DocImage src={SwapWidgetLight} />
+</div>
+
+## Features
+
+- Cross-chain token swaps across 90+ blockchains
+- Route optimization to find the best path for any token pair
+- Customizable UI - use prebuilt themes or override with your brand colors
+- Display fiat values in multiple currencies
+
+## Example
+
+You will need a thirdweb project client id to use the `SwapWidget` component. You can get your clientId by creating a project in the [thirdweb dashboard](https://thirdweb.com/team).
+
+```tsx
+import { SwapWidget } from "thirdweb/react";
+import { createThirdwebClient } from "thirdweb";
+
+const client = createThirdwebClient({
+  clientId: "YOUR_THIRDWEB_CLIENT_ID",
+});
+
+function Example() {
+  return <SwapWidget client={client} />;
+}
+```
+
+Make sure to wrap the component containing `SwapWidget` with the `ThirdwebProvider` component.
+
+```tsx
+import { ThirdwebProvider } from "thirdweb/react";
+
+function App() {
+  return (
+    <ThirdwebProvider>
+      <YourApp />
+    </ThirdwebProvider>
+  );
+}
+```
+
+## Configuring default Token Selection
+
+By default, no tokens are selected in the widget UI. You can configure the default token selection by passing in the `prefill` prop. It only sets the default token selection - users can change these selections in the widget UI.
+
+### Set an ERC20 token to Buy by default
+
+```tsx
+<SwapWidget
+  client={client}
+  prefill={{
+    buyToken: {
+      // Base USDC
+      chainId: 8453,
+      tokenAddress: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+    },
+  }}
+/>
+```
+
+### Set a native token to Sell by default
+
+To configure a native token to sell by default, you can omit the `tokenAddress` property.
+
+```tsx
+<SwapWidget
+  client={client}
+  prefill={{
+    // Base native token (ETH)
+    sellToken: {
+      chainId: 8453,
+    },
+  }}
+/>
+```
+
+### Set amount and token to Buy by default
+
+```tsx
+<SwapWidget
+  client={client}
+  prefill={{
+    buyToken: {
+      chainId: 8453,
+      amount: "0.1",
+      tokenAddress: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+    },
+  }}
+/>
+```
+
+### Set both buy and sell tokens by default
+
+```tsx
+<SwapWidget
+  client={client}
+  prefill={{
+    // Base USDC
+    buyToken: {
+      chainId: 8453,
+      tokenAddress: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+    },
+    // Polygon native token (POL)
+    sellToken: {
+      chainId: 137,
+    },
+  }}
+/>
+```
+
+## API Reference
+
+<ArticleIconCard
+  title="SwapWidget Component"
+  description="View the API reference for the SwapWidget component"
+  icon={ReactIcon}
+  href="/references/typescript/v5/SwapWidget"
+/>
+
+## Try it out
+
+<ArticleIconCard
+	title="Swap Widget Playground"
+	description="Try out the Swap Widget in our live playground"
+	icon={PlayIcon}
+	href="https://playground.thirdweb.com/bridge/swap-widget?tab=react"
+/>
+