Skip to content

Commit f344fb5

Browse files
MananTankMananTank
committed
[MNY-351] Portal: Add swap widget iframe docs (#8604)
<!-- ## 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 -->
1 parent 9f265bf commit f344fb5

File tree

5 files changed

+389
-111
lines changed

5 files changed

+389
-111
lines changed

‎apps/portal/src/app/bridge/sidebar.tsx‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,16 @@ export const sidebar: SideBar = {
5757
{
5858
name: "Swap Widget",
5959
href: `${bridgeSlug}/swap-widget`,
60+
links: [
61+
{
62+
href: `${bridgeSlug}/swap-widget/react`,
63+
name: "React Component",
64+
},
65+
{
66+
href: `${bridgeSlug}/swap-widget/iframe`,
67+
name: "Iframe",
68+
},
69+
],
6070
},
6171
],
6272
},

‎apps/portal/src/app/bridge/swap-widget/iframe/iframe-code-preview.tsx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
import { CodeBlock, Tabs, TabsContent, TabsList, TabsTrigger } from "@doc";
2+
3+
export function IframeCodePreview(props: { src: string }) {
4+
return (
5+
<Tabs defaultValue="code">
6+
<TabsList>
7+
<TabsTrigger value="code">Code</TabsTrigger>
8+
<TabsTrigger value="preview">Preview</TabsTrigger>
9+
</TabsList>
10+
<TabsContent value="code">
11+
<CodeBlock
12+
code={`\
13+
<iframe
14+
src="${props.src}"
15+
height="750px"
16+
width="100%"
17+
style="border: 0;"
18+
/>`}
19+
lang="html"
20+
/>
21+
</TabsContent>
22+
<TabsContent value="preview">
23+
<iframe
24+
title="Swap widget iframe"
25+
src={props.src}
26+
height="750px"
27+
className="rounded-xl"
28+
width="100%"
29+
style={{ border: 0 }}
30+
/>
31+
</TabsContent>
32+
</Tabs>
33+
);
34+
}

‎apps/portal/src/app/bridge/swap-widget/iframe/page.mdx‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
import {
2+
ArticleIconCard,
3+
Details,
4+
createMetadata,
5+
DocImage,
6+
} from "@doc";
7+
import { IframeCodePreview } from "./iframe-code-preview";
8+
import { PlayIcon } from "lucide-react";
9+
import SwapWidgetDark from "../../swap/swap-dark.jpg";
10+
import SwapWidgetLight from "../../swap/swap-light.jpg";
11+
12+
export const metadata = createMetadata({
13+
image: {
14+
title: "Swap widget iframe",
15+
icon: "payments",
16+
},
17+
title: "Swap widget iframe",
18+
description: "Add a widget to swap tokens across chains using an iframe",
19+
});
20+
21+
# Swap widget iframe
22+
23+
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.
24+
25+
<div className='dark-only'>
26+
<DocImage src={SwapWidgetDark} />
27+
</div>
28+
<div className='light-only'>
29+
<DocImage src={SwapWidgetLight} />
30+
</div>
31+
32+
## Features
33+
34+
- Cross-chain token swaps across 90+ blockchains
35+
- Route optimization to find the best path for any token pair
36+
- Dark and light mode support
37+
- Display fiat values in multiple currencies
38+
39+
## Iframe Integration
40+
41+
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.
42+
43+
### Example
44+
45+
46+
<IframeCodePreview src="https://thirdweb.com/bridge/swap-widget" />
47+
48+
## Try it out
49+
50+
<ArticleIconCard
51+
title="Swap Widget Playground"
52+
description="Try out the Swap Widget in our live playground"
53+
icon={PlayIcon}
54+
href="https://playground.thirdweb.com/bridge/swap-widget?tab=iframe"
55+
/>
56+
57+
## Options
58+
59+
You can customize the swap widget using query parameters as mentioned below.
60+
61+
### Token Selection
62+
63+
You can prefill the buy and sell token selections using the following parameters:
64+
65+
| Parameter | Description |
66+
|-----------|-------------|
67+
| `buyChain` | Chain ID for the buy token (e.g., 1 for Ethereum, 8453 for Base) |
68+
| `buyTokenAddress` | Token contract address for the buy token. If not set, native token is used |
69+
| `buyAmount` | Default amount to buy |
70+
| `sellChain` | Chain ID for the sell token |
71+
| `sellTokenAddress` | Token contract address for the sell token. If not set, native token is used |
72+
| `sellAmount` | Default amount to sell |
73+
74+
<Details summary="Set sell token to Base USDC">
75+
76+
<IframeCodePreview src="https://thirdweb.com/bridge/swap-widget?sellChain=8453&sellTokenAddress=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" />
77+
78+
</Details>
79+
80+
<Details summary="Set buy token to Ethereum native (ETH)">
81+
82+
<IframeCodePreview src="https://thirdweb.com/bridge/swap-widget?buyChain=1" />
83+
84+
</Details>
85+
86+
<Details summary="Set both buy and sell tokens">
87+
88+
<IframeCodePreview src="https://thirdweb.com/bridge/swap-widget?sellChain=8453&sellTokenAddress=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913&buyChain=137" />
89+
90+
</Details>
91+
92+
### Theme
93+
94+
By default the widget uses the "dark" theme. You can set the light theme by passing the `theme=light` query parameter.
95+
96+
<IframeCodePreview src="https://thirdweb.com/bridge/swap-widget?theme=light&sellChain=8453" />
97+
98+
99+
### Currency
100+
101+
By default the fiat value of the token amounts is displayed in USD. You can change the currency by setting the `currency` query parameter.
102+
103+
<Details summary="Supported Currencies">
104+
105+
- `USD` - US Dollar (default)
106+
- `EUR` - Euro
107+
- `GBP` - British Pound
108+
- `JPY` - Japanese Yen
109+
- `KRW` - Korean Won
110+
- `CNY` - Chinese Yuan
111+
- `INR` - Indian Rupee
112+
- `NOK` - Norwegian Krone
113+
- `SEK` - Swedish Krona
114+
- `CHF` - Swiss Franc
115+
- `AUD` - Australian Dollar
116+
- `CAD` - Canadian Dollar
117+
- `NZD` - New Zealand Dollar
118+
- `MXN` - Mexican Peso
119+
- `BRL` - Brazilian Real
120+
- `CLP` - Chilean Peso
121+
- `CZK` - Czech Koruna
122+
- `DKK` - Danish Krone
123+
- `HKD` - Hong Kong Dollar
124+
- `HUF` - Hungarian Forint
125+
- `IDR` - Indonesian Rupiah
126+
- `ILS` - Israeli New Sheqel
127+
- `ISK` - Icelandic Krona
128+
129+
</Details>
130+
131+
#### Example
132+
133+
Show fiat values in Euro (EUR) in the widget.
134+
135+
<IframeCodePreview src="https://thirdweb.com/bridge/swap-widget?sellChain=8453&currency=EUR" />
136+
137+
### thirdweb branding
138+
139+
By default, the widget displays thirdweb branding at the bottom. You can hide this by setting the `showThirdwebBranding` query parameter to `false`.
140+
141+
<IframeCodePreview src="https://thirdweb.com/bridge/swap-widget?sellChain=8453&showThirdwebBranding=false" />
142+
143+
## Listening for Events
144+
145+
The swap widget iframe sends events to the parent window using `postMessage` when a swap succeeds or fails.
146+
147+
You can listen for these events to handle the swap result in your application.
148+
149+
```js
150+
window.addEventListener("message", (event) => {
151+
152+
// verify that message is from thirdweb swap widget iframe
153+
if (
154+
event.origin === "https://thirdweb.com" && event.data.source === "swap-widget"
155+
) {
156+
157+
if (event.data.type === "success") {
158+
console.log("Swap successful!");
159+
}
160+
161+
if (event.data.type === "error") {
162+
console.error("Swap failed with error:", event.data.message);
163+
}
164+
}
165+
166+
});
167+
```
168+

‎apps/portal/src/app/bridge/swap-widget/page.mdx‎

Lines changed: 22 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import {
33
createMetadata,
44
DocImage,
55
} from "@doc";
6-
import { PlayIcon } from "lucide-react";
6+
import { FrameIcon, PlayIcon } from "lucide-react";
77
import { ReactIcon } from "@/icons";
88
import SwapWidgetDark from "../swap/swap-dark.jpg";
99
import SwapWidgetLight from "../swap/swap-light.jpg";
@@ -19,7 +19,7 @@ export const metadata = createMetadata({
1919

2020
# Swap widget
2121

22-
The Swap widget makes it easy to add cross-chain token swaps to your app using the thirdweb SDK.
22+
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.
2323

2424
<div className='dark-only'>
2525
<DocImage src={SwapWidgetDark} />
@@ -30,128 +30,39 @@ The Swap widget makes it easy to add cross-chain token swaps to your app using t
3030

3131
## Features
3232

33-
- Cross-chain token swaps across 50+ blockchains
34-
- Real-time quotes with up-to-date pricing
33+
- Cross-chain token swaps across 90+ blockchains
3534
- Route optimization to find the best path for any token pair
36-
- Customizable UI - use prebuilt themes or override with your brand colors
35+
- Customizable UI with dark and light mode support
3736
- Prefill token selections for a smoother user experience
38-
- Event callbacks to track user actions (success, error, cancel)
37+
- Display fiat values in multiple currencies
3938

40-
## Example
39+
## Get Started
4140

42-
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).
41+
You can integrate the swap widget into your website using an iframe or a React component.
4342

44-
```tsx
45-
import { SwapWidget } from "thirdweb/react";
46-
import { createThirdwebClient } from "thirdweb";
43+
<div className="space-y-4">
4744

48-
const client = createThirdwebClient({
49-
clientId: "YOUR_THIRDWEB_CLIENT_ID",
50-
});
51-
52-
function Example() {
53-
return <SwapWidget client={client} />;
54-
}
55-
```
56-
57-
Make sure to wrap the component containing `SwapWidget` with the `ThirdwebProvider` component.
58-
59-
```tsx
60-
import { ThirdwebProvider } from "thirdweb/react";
61-
62-
function App() {
63-
return (
64-
<ThirdwebProvider>
65-
<YourApp />
66-
</ThirdwebProvider>
67-
);
68-
}
69-
```
70-
71-
## Configuring Default Token Selection
72-
73-
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.
74-
75-
### Set an ERC20 token to Buy by default
76-
77-
```tsx
78-
<SwapWidget
79-
client={client}
80-
prefill={{
81-
buyToken: {
82-
// Base USDC
83-
chainId: 8453,
84-
tokenAddress: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
85-
},
86-
}}
87-
/>
88-
```
89-
90-
### Set a native token to Sell by default
91-
92-
To configure a native token to sell by default, you can omit the `tokenAddress` property.
93-
94-
```tsx
95-
<SwapWidget
96-
client={client}
97-
prefill={{
98-
// Base native token (ETH)
99-
sellToken: {
100-
chainId: 8453,
101-
},
102-
}}
103-
/>
104-
```
105-
106-
### Set amount and token to Buy by default
107-
108-
```tsx
109-
<SwapWidget
110-
client={client}
111-
prefill={{
112-
buyToken: {
113-
chainId: 8453,
114-
amount: "0.1",
115-
tokenAddress: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
116-
},
117-
}}
118-
/>
119-
```
120-
121-
### Set both buy and sell tokens by default
122-
123-
```tsx
124-
<SwapWidget
125-
client={client}
126-
prefill={{
127-
// Base USDC
128-
buyToken: {
129-
chainId: 8453,
130-
tokenAddress: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
131-
},
132-
// Polygon native token (POL)
133-
sellToken: {
134-
chainId: 137,
135-
},
136-
}}
45+
<ArticleIconCard
46+
title="Iframe"
47+
icon={FrameIcon}
48+
description="Integrate swap widget into your website using an iframe"
49+
href="/bridge/swap-widget/iframe"
13750
/>
138-
```
139-
140-
## API Reference
14151

14252
<ArticleIconCard
143-
title="SwapWidget Component"
144-
description="View the API reference for the SwapWidget component"
53+
title="React Component"
14554
icon={ReactIcon}
146-
href="/references/typescript/v5/SwapWidget"
55+
description="Integrate swap widget into your app using a React component"
56+
href="/bridge/swap-widget/react"
14757
/>
14858

59+
</div>
60+
14961
## Try it out
15062

15163
<ArticleIconCard
152-
title="Swap Widget Playground"
153-
description="Try out the Swap Widget in our live playground"
154-
icon={PlayIcon}
155-
href="https://playground.thirdweb.com/bridge/swap-widget"
64+
title="Swap Widget Playground"
65+
description="Try out the Swap Widget in our live playground"
66+
icon={PlayIcon}
67+
href="https://playground.thirdweb.com/bridge/swap-widget"
15668
/>
157-

0 commit comments

Comments
 (0)