From c1275a5e3893685cf2832dcdae4ce39c01e286db Mon Sep 17 00:00:00 2001
From: MananTank <manantankm@gmail.com>
Date: Wed, 7 Jan 2026 20:23:14 +0000
Subject: [PATCH] [MNY-354] Portal: Add Buy Widget iframe docs (#8614)
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 introduces the `Buy Widget`, enhancing the portal with a new iframe component for purchasing crypto. It includes documentation, features, and examples for users to integrate the widget easily.

### Detailed summary
- Added `IframeCodePreview` component in `iframe-code-preview.tsx`.
- Updated sidebar links to reflect the new `Buy Widget` and `Swap Widget`.
- Created documentation for the `Buy Widget` in `page.mdx`, detailing features and integration.
- Added example usage of the `BuyWidget` component in `react/page.mdx`.
- Developed `iframe/page.mdx` with customization options and event listening for the widget.

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

<!-- end pr-codex -->

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
## Summary by CodeRabbit

* **New Features**
  * Added an iframe embed preview with code/preview tabs for trying the Buy widget.

* **Documentation**
  * Added comprehensive Buy widget docs (overview, React and iframe guides, examples, customization, event listening, live playgrounds).

* **Chores**
  * Updated site navigation: Widgets section reorganized to list Swap, Buy, and Checkout widgets with updated links.

<sub>✏️ Tip: You can customize this high-level summary in your review settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 .../buy-widget/iframe/iframe-code-preview.tsx |  36 ++++
 .../src/app/bridge/buy-widget/iframe/page.mdx | 168 ++++++++++++++++++
 .../portal/src/app/bridge/buy-widget/page.mdx |  61 +++++++
 .../src/app/bridge/buy-widget/react/page.mdx  | 127 +++++++++++++
 apps/portal/src/app/bridge/sidebar.tsx        |  30 +++-
 5 files changed, 414 insertions(+), 8 deletions(-)
 create mode 100644 apps/portal/src/app/bridge/buy-widget/iframe/iframe-code-preview.tsx
 create mode 100644 apps/portal/src/app/bridge/buy-widget/iframe/page.mdx
 create mode 100644 apps/portal/src/app/bridge/buy-widget/page.mdx
 create mode 100644 apps/portal/src/app/bridge/buy-widget/react/page.mdx

diff --git a/apps/portal/src/app/bridge/buy-widget/iframe/iframe-code-preview.tsx b/apps/portal/src/app/bridge/buy-widget/iframe/iframe-code-preview.tsx
new file mode 100644
index 00000000000..5b2375bb4d9
--- /dev/null
+++ b/apps/portal/src/app/bridge/buy-widget/iframe/iframe-code-preview.tsx
@@ -0,0 +1,36 @@
+import { CodeBlock, Tabs, TabsContent, TabsList, TabsTrigger } from "@doc";
+
+export function IframeCodePreview(props: { src: string }) {
+  const includesImage = props.src.includes("image=");
+  const height = includesImage ? "850px" : "700px";
+  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="${height}"
+  width="100%"
+  style="border: 0;"
+/>`}
+          lang="html"
+        />
+      </TabsContent>
+      <TabsContent value="preview">
+        <iframe
+          title="Buy widget iframe"
+          src={props.src}
+          height={height}
+          className="rounded-xl"
+          width="100%"
+          style={{ border: 0 }}
+        />
+      </TabsContent>
+    </Tabs>
+  );
+}
diff --git a/apps/portal/src/app/bridge/buy-widget/iframe/page.mdx b/apps/portal/src/app/bridge/buy-widget/iframe/page.mdx
new file mode 100644
index 00000000000..28794cc5440
--- /dev/null
+++ b/apps/portal/src/app/bridge/buy-widget/iframe/page.mdx
@@ -0,0 +1,168 @@
+import {
+  ArticleIconCard,
+  Details,
+  createMetadata,
+} from "@doc";
+import { IframeCodePreview } from "./iframe-code-preview";
+import { PlayIcon } from "lucide-react";
+
+export const metadata = createMetadata({
+  image: {
+    title: "Buy widget iframe",
+    icon: "payments",
+  },
+  title: "Buy widget iframe",
+  description: "Add a widget to let users buy crypto in your app using an iframe",
+});
+
+# Buy widget iframe
+
+The Buy widget iframe makes it easy for users to purchase crypto tokens in your app. Just add an iframe to your HTML and get a fully customizable buy widget - no build setup required.
+
+## Features
+
+- Purchase crypto tokens with fiat (credit/debit cards)
+- Cross-chain token swaps across 90+ blockchains
+- Display product information (title, description, image)
+- Customizable UI with dark and light mode support
+- Display fiat values in multiple currencies
+
+
+### Example
+
+
+<IframeCodePreview src="https://thirdweb.com/bridge/buy-widget" />
+
+
+## Try it out
+
+<ArticleIconCard
+	title="Buy Widget Playground"
+	description="Try out the Buy Widget in our live playground"
+	icon={PlayIcon}
+	href="https://playground.thirdweb.com/bridge/buy-widget?tab=iframe"
+/>
+
+## Options
+
+You can customize the buy widget using query parameters as mentioned below.
+
+
+### 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/buy-widget?theme=light" />
+
+
+### Product Information
+
+You can display product information by passing `title`, `description`, and `image` query parameters. Each of these parameters are optional.
+
+Make sure to URI encode the parameters if they contain special characters.
+
+<Details summary="Example">
+
+* title: `"Something"`
+* description: `"Description of something goes here"`
+* image: `"https://picsum.photos/600/300"`
+* price: 0.01 ETH on Base
+
+<IframeCodePreview src="https://thirdweb.com/bridge/buy-widget?chain=8453&amount=0.01&title=Something&description=Description%20of%20something%20goes%20here&image=https%3A%2F%2Fpicsum.photos%2F600%2F300" />
+
+</Details>
+
+
+### 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/buy-widget?currency=EUR" />
+
+### Payment Methods
+
+By default, the widget enables both crypto and card (fiat) payment methods.
+
+You can customize which payment methods are available by setting the `paymentMethods` query parameter.
+
+Accepted values:
+- `crypto` - Enable crypto payments only
+- `card` - Enable card (fiat) payments only
+
+<Details summary="Only enable crypto payments">
+
+<IframeCodePreview src="https://thirdweb.com/bridge/buy-widget?paymentMethods=crypto" />
+
+</Details>
+
+
+<Details summary="Only enable card payments">
+
+<IframeCodePreview src="https://thirdweb.com/bridge/buy-widget?paymentMethods=card" />
+
+</Details>
+
+### 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/buy-widget?showThirdwebBranding=false" />
+
+## Listening for Events
+
+The buy widget iframe sends events to the parent window using `postMessage` when a purchase succeeds or fails.
+
+You can listen for these events to handle the purchase result in your application.
+
+```js
+window.addEventListener("message", (event) => {
+
+  // verify that message is from thirdweb buy widget iframe
+  if (
+    event.origin === "https://thirdweb.com" && event.data.source === "buy-widget"
+  ) {
+
+  if (event.data.type === "success") {
+    console.log("Purchase successful!");
+  }
+
+  if (event.data.type === "error") {
+    console.error("Purchase failed with error:", event.data.message);
+  }
+  }
+
+});
+```
+
diff --git a/apps/portal/src/app/bridge/buy-widget/page.mdx b/apps/portal/src/app/bridge/buy-widget/page.mdx
new file mode 100644
index 00000000000..d475864dfb5
--- /dev/null
+++ b/apps/portal/src/app/bridge/buy-widget/page.mdx
@@ -0,0 +1,61 @@
+import {
+  Details,
+  createMetadata,
+  DocImage,
+} from "@doc";
+import { ArticleIconCard } from "@doc";
+import { FrameIcon, PlayIcon } from "lucide-react";
+import { ReactIcon } from "@/icons";
+
+export const metadata = createMetadata({
+  image: {
+    title: "Buy widget",
+    icon: "payments",
+  },
+  title: "Buy widget",
+  description: "Add a widget to let users buy crypto in your app",
+});
+
+# Buy widget
+
+The Buy widget makes it easy for users to purchase crypto tokens in your app. It supports both fiat payments (credit/debit cards) and crypto payments, with cross-chain support across 90+ blockchains.
+
+## Features
+
+- Purchase crypto tokens with fiat (credit/debit cards)
+- Cross-chain token swaps across 90+ blockchains
+- Display product information (title, description, image)
+- Customizable UI with dark and light mode support
+- Display fiat values in multiple currencies
+
+## Get Started
+
+You can integrate the buy widget into your website using an iframe or a React component.
+
+<div className="space-y-4">
+
+<ArticleIconCard
+	title="Iframe"
+  icon={FrameIcon}
+	description="Integrate buy widget into your website using an iframe"
+	href="/bridge/buy-widget/iframe"
+/>
+
+<ArticleIconCard
+	title="React Component"
+  icon={ReactIcon}
+	description="Integrate buy widget into your app using a React component"
+	href="/bridge/buy-widget/react"
+/>
+
+</div>
+
+## Try it out
+
+<ArticleIconCard
+	title="Buy Widget Playground"
+	description="Try out the Buy Widget in our live playground"
+	icon={PlayIcon}
+	href="https://playground.thirdweb.com/bridge/buy-widget"
+/>
+
diff --git a/apps/portal/src/app/bridge/buy-widget/react/page.mdx b/apps/portal/src/app/bridge/buy-widget/react/page.mdx
new file mode 100644
index 00000000000..eb9bec6e5bb
--- /dev/null
+++ b/apps/portal/src/app/bridge/buy-widget/react/page.mdx
@@ -0,0 +1,127 @@
+import {
+  ArticleIconCard,
+  createMetadata,
+} from "@doc";
+import { PlayIcon } from "lucide-react";
+import { ReactIcon } from "@/icons";
+
+export const metadata = createMetadata({
+  image: {
+    title: "Buy widget component",
+    icon: "payments",
+  },
+  title: "Buy widget component",
+  description: "Add a widget to let users buy crypto in your app using a React component",
+});
+
+# Buy widget component
+
+The Buy widget component makes it easy for users to purchase crypto tokens in your app
+
+## Features
+
+- Purchase crypto tokens with fiat (credit/debit cards)
+- Cross-chain token swaps across 90+ blockchains
+- Display product information (title, description, image)
+- Customizable UI with dark and light mode support
+- Display fiat values in multiple currencies
+
+## Example
+
+You will need a thirdweb project client id to use the `BuyWidget` component. You can get your clientId by creating a project in the [thirdweb dashboard](https://thirdweb.com/team).
+
+```tsx
+import { BuyWidget } from "thirdweb/react";
+import { createThirdwebClient } from "thirdweb";
+import { base } from "thirdweb/chains";
+
+const client = createThirdwebClient({
+  clientId: "YOUR_THIRDWEB_CLIENT_ID",
+});
+
+function Example() {
+  return (
+    <BuyWidget
+      client={client}
+      chain={base}
+      amount="0.01"
+    />
+  );
+}
+```
+
+Make sure to wrap the component containing `BuyWidget` with the `ThirdwebProvider` component.
+
+```tsx
+import { ThirdwebProvider } from "thirdweb/react";
+
+function App() {
+  return (
+    <ThirdwebProvider>
+      <YourApp />
+    </ThirdwebProvider>
+  );
+}
+```
+
+### Prefill a specific token
+
+You can prefill the widget with a specific token by passing the `tokenAddress` prop.
+
+```tsx
+import { BuyWidget } from "thirdweb/react";
+import { base } from "thirdweb/chains";
+
+function Example() {
+  return (
+    <BuyWidget
+      client={client}
+      chain={base}
+      // USDC on Base
+      tokenAddress="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+      amount="10"
+    />
+  );
+}
+```
+
+### Send to a specific address
+
+By default, the connected wallet address receives the purchased tokens.
+
+You can set `receiverAddress` prop to send the purchased tokens to a different address.
+
+```tsx
+import { BuyWidget } from "thirdweb/react";
+import { base } from "thirdweb/chains";
+
+function Example() {
+  return (
+    <BuyWidget
+      client={client}
+      chain={base}
+      amount="0.01"
+      receiverAddress="0x123...abc"
+    />
+  );
+}
+```
+
+## API Reference
+
+<ArticleIconCard
+  title="BuyWidget Component"
+  description="View the API reference for the BuyWidget component"
+  icon={ReactIcon}
+  href="/references/typescript/v5/BuyWidget"
+/>
+
+## Try it out
+
+<ArticleIconCard
+	title="Buy Widget Playground"
+	description="Try out the Buy Widget in our live playground"
+	icon={PlayIcon}
+	href="https://playground.thirdweb.com/bridge/buy-widget?tab=react"
+/>
+
diff --git a/apps/portal/src/app/bridge/sidebar.tsx b/apps/portal/src/app/bridge/sidebar.tsx
index f26740aed07..76c3b6b397f 100644
--- a/apps/portal/src/app/bridge/sidebar.tsx
+++ b/apps/portal/src/app/bridge/sidebar.tsx
@@ -41,29 +41,43 @@ export const sidebar: SideBar = {
           ],
         },
         {
-          name: "Checkout Widget",
-          href: `${bridgeSlug}/checkout-widget`,
+          name: "Swap Widget",
+          href: `${bridgeSlug}/swap-widget`,
           links: [
             {
-              href: `${bridgeSlug}/checkout-widget/react`,
+              href: `${bridgeSlug}/swap-widget/react`,
               name: "React Component",
             },
             {
-              href: `${bridgeSlug}/checkout-widget/iframe`,
+              href: `${bridgeSlug}/swap-widget/iframe`,
               name: "Iframe",
             },
           ],
         },
         {
-          name: "Swap Widget",
-          href: `${bridgeSlug}/swap-widget`,
+          name: "Buy Widget",
+          href: `${bridgeSlug}/buy-widget`,
           links: [
             {
-              href: `${bridgeSlug}/swap-widget/react`,
+              href: `${bridgeSlug}/buy-widget/react`,
               name: "React Component",
             },
             {
-              href: `${bridgeSlug}/swap-widget/iframe`,
+              href: `${bridgeSlug}/buy-widget/iframe`,
+              name: "Iframe",
+            },
+          ],
+        },
+        {
+          name: "Checkout Widget",
+          href: `${bridgeSlug}/checkout-widget`,
+          links: [
+            {
+              href: `${bridgeSlug}/checkout-widget/react`,
+              name: "React Component",
+            },
+            {
+              href: `${bridgeSlug}/checkout-widget/iframe`,
               name: "Iframe",
             },
           ],