Skip to content

[MNY-351] Portal: Add swap widget iframe docs #8604

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
graphite-app merged 1 commit into from
Jan 5, 2026
+389 −111
Merged

[MNY-351] Portal: Add swap widget iframe docs #8604

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions apps/portal/src/app/bridge/sidebar.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
},
],
},
],
},
Expand Down
34 changes: 34 additions & 0 deletions apps/portal/src/app/bridge/swap-widget/iframe/iframe-code-preview.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>
);
}
168 changes: 168 additions & 0 deletions apps/portal/src/app/bridge/swap-widget/iframe/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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);
}
}

});
```

133 changes: 22 additions & 111 deletions apps/portal/src/app/bridge/swap-widget/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand All @@ -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} />
Expand All @@ -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"
/>

Loading
Loading