[MNY-356] Add tokenEditable and amountEditable props on BuyWidget (#8621)

MananTank · MananTank · commit 8d4b6a1fea53 · 2026-01-12T18:12:38.000Z
&lt;!--

## 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.

--&gt;

&lt;!-- start pr-codex --&gt;

---

## PR-Codex overview
This PR introduces two new properties, `amountEditable` and `tokenEditable`, to enhance the `BuyWidget` component, allowing control over editing options for token selection and amount. This improves user experience by providing flexibility in the widget's functionality.

### Detailed summary
- Added `amountEditable` and `tokenEditable` properties to `BuyWidget`.
- Updated `BuyPlayground.tsx`, `CheckoutPlayground.tsx`, and `TransactionPlayground.tsx` to use new props.
- Modified `CodeGen.tsx` to incorporate editability options.
- Updated URL generation in `buildBuyIframeUrl.ts` for new props.
- Added editability options in `LeftSection.tsx`.
- Enhanced `BuyWidgetEmbed` to accept new props.
- Implemented stories in `BuyWidget.stories.tsx` for editable and non-editable states.
- Added documentation in `iframe/page.mdx` for new features.
- Adjusted `FundWallet.tsx` and `TokenSection.tsx` to respect new editability options.

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

&lt;!-- end pr-codex --&gt;

&lt;!-- This is an auto-generated comment: release notes by coderabbit.ai --&gt;

## Summary by CodeRabbit

## Release Notes

* **New Features**
  * Added `amountEditable` and `tokenEditable` props to the BuyWidget component, allowing developers to disable token selection and/or amount editing in the buy flow.
  * Enhanced UI controls to prevent interaction with locked fields when these options are disabled.
  * Updated documentation with examples of how to use the new editability options.

* **Tests**
  * Added story variants demonstrating token and amount lock scenarios.

&lt;sub&gt;✏️ Tip: You can customize this high-level summary in your review settings.&lt;/sub&gt;

&lt;!-- end of auto-generated comment: release notes by coderabbit.ai --&gt;
diff --git a/.changeset/dirty-breads-swim.md b/.changeset/dirty-breads-swim.md
@@ -0,0 +1,5 @@
+---
+"thirdweb": patch
+---
+
+Add `amountEditable` and `tokenEditable` props on `BuyWidget` component to disable token selection and token amount editing
diff --git a/apps/dashboard/src/app/bridge/buy-widget/BuyWidgetEmbed.client.tsx b/apps/dashboard/src/app/bridge/buy-widget/BuyWidgetEmbed.client.tsx
@@ -20,6 +20,8 @@ export function BuyWidgetEmbed({
   buttonLabel,
   receiverAddress,
   country,
+  amountEditable,
+  tokenEditable,
 }: {
   chainId?: number;
   tokenAddress?: Address;
@@ -34,6 +36,8 @@ export function BuyWidgetEmbed({
   buttonLabel?: string;
   receiverAddress?: Address;
   country?: string;
+  amountEditable?: boolean;
+  tokenEditable?: boolean;
 }) {
   const client = useMemo(
     () =>
@@ -68,6 +72,8 @@ export function BuyWidgetEmbed({
       buttonLabel={buttonLabel}
       receiverAddress={receiverAddress}
       country={country}
+      amountEditable={amountEditable}
+      tokenEditable={tokenEditable}
       onSuccess={() => {
         sendMessageToParent({
           source: "buy-widget",
diff --git a/apps/dashboard/src/app/bridge/buy-widget/page.tsx b/apps/dashboard/src/app/bridge/buy-widget/page.tsx
@@ -73,6 +73,14 @@ export default async function Page(props: {
   const receiverAddress = parseQueryParams(searchParams.receiver, onlyAddress);
   const country = parseQueryParams(searchParams.country, (v) => v);
 
+  // Editable params
+  const amountEditable = parseQueryParams(searchParams.amountEditable, (v) =>
+    v === "false" ? false : undefined,
+  );
+  const tokenEditable = parseQueryParams(searchParams.tokenEditable, (v) =>
+    v === "false" ? false : undefined,
+  );
+
   return (
     <BridgeProvidersLite forcedTheme={theme}>
       <div className="flex min-h-screen items-center justify-center bg-background px-4 py-8">
@@ -90,6 +98,8 @@ export default async function Page(props: {
           buttonLabel={buttonLabel}
           receiverAddress={receiverAddress}
           country={country}
+          amountEditable={amountEditable}
+          tokenEditable={tokenEditable}
         />
       </div>
     </BridgeProvidersLite>
diff --git a/apps/playground-web/src/app/bridge/buy-widget/BuyPlayground.tsx b/apps/playground-web/src/app/bridge/buy-widget/BuyPlayground.tsx
@@ -24,6 +24,8 @@ const defaultOptions: BridgeComponentsPlaygroundOptions = {
     transactionData: "",
     currency: "USD",
     showThirdwebBranding: true,
+    amountEditable: true,
+    tokenEditable: true,
   },
   theme: {
     darkColorOverrides: {},
diff --git a/apps/playground-web/src/app/bridge/checkout-widget/CheckoutPlayground.tsx b/apps/playground-web/src/app/bridge/checkout-widget/CheckoutPlayground.tsx
@@ -24,6 +24,8 @@ const defaultOptions: BridgeComponentsPlaygroundOptions = {
     receiverAddress: undefined,
     currency: "USD",
     showThirdwebBranding: true,
+    amountEditable: true,
+    tokenEditable: true,
   },
   theme: {
     darkColorOverrides: {},
diff --git a/apps/playground-web/src/app/bridge/components/CodeGen.tsx b/apps/playground-web/src/app/bridge/components/CodeGen.tsx
@@ -160,6 +160,14 @@ tokenId: 2n,
       ? quotes(options.payOptions.buttonLabel)
       : undefined,
     transaction: transaction,
+    amountEditable:
+      widget === "buy" && options.payOptions.amountEditable === false
+        ? false
+        : undefined,
+    tokenEditable:
+      widget === "buy" && options.payOptions.tokenEditable === false
+        ? false
+        : undefined,
   };
 
   return `\
diff --git a/apps/playground-web/src/app/bridge/components/LeftSection.tsx b/apps/playground-web/src/app/bridge/components/LeftSection.tsx
@@ -259,6 +259,46 @@ export function LeftSection(props: {
                     </div>
                   </div>
                 </div>
+
+                {/* Editability Options */}
+                <div className="flex flex-col gap-3">
+                  <Label>Editability Options</Label>
+                  <div className="flex gap-4">
+                    <div className="flex items-center space-x-2">
+                      <Checkbox
+                        checked={payOptions.tokenEditable}
+                        id="token-editable"
+                        onCheckedChange={(checked) => {
+                          setOptions((v) => ({
+                            ...v,
+                            payOptions: {
+                              ...v.payOptions,
+                              tokenEditable: checked === true,
+                            },
+                          }));
+                        }}
+                      />
+                      <Label htmlFor="token-editable">Token Editable</Label>
+                    </div>
+
+                    <div className="flex items-center space-x-2">
+                      <Checkbox
+                        checked={payOptions.amountEditable}
+                        id="amount-editable"
+                        onCheckedChange={(checked) => {
+                          setOptions((v) => ({
+                            ...v,
+                            payOptions: {
+                              ...v.payOptions,
+                              amountEditable: checked === true,
+                            },
+                          }));
+                        }}
+                      />
+                      <Label htmlFor="amount-editable">Amount Editable</Label>
+                    </div>
+                  </div>
+                </div>
               </div>
             )}
 
diff --git a/apps/playground-web/src/app/bridge/components/RightSection.tsx b/apps/playground-web/src/app/bridge/components/RightSection.tsx
@@ -70,6 +70,8 @@ export function RightSection(props: {
         currency={props.options.payOptions.currency}
         showThirdwebBranding={props.options.payOptions.showThirdwebBranding}
         receiverAddress={props.options.payOptions.receiverAddress}
+        amountEditable={props.options.payOptions.amountEditable}
+        tokenEditable={props.options.payOptions.tokenEditable}
         key={JSON.stringify({
           amount: props.options.payOptions.buyTokenAmount,
           chain: props.options.payOptions.buyTokenChain,
diff --git a/apps/playground-web/src/app/bridge/components/buildBuyIframeUrl.ts b/apps/playground-web/src/app/bridge/components/buildBuyIframeUrl.ts
@@ -68,5 +68,14 @@ export function buildBuyIframeUrl(options: BridgeComponentsPlaygroundOptions) {
     );
   }
 
+  // Editability options
+  if (options.payOptions.amountEditable === false) {
+    url.searchParams.set("amountEditable", "false");
+  }
+
+  if (options.payOptions.tokenEditable === false) {
+    url.searchParams.set("tokenEditable", "false");
+  }
+
   return url.toString();
 }
diff --git a/apps/playground-web/src/app/bridge/components/types.ts b/apps/playground-web/src/app/bridge/components/types.ts
@@ -59,5 +59,9 @@ export type BridgeComponentsPlaygroundOptions = {
     currency?: SupportedFiatCurrency;
 
     showThirdwebBranding: boolean;
+
+    // Editability options
+    amountEditable: boolean;
+    tokenEditable: boolean;
   };
 };
diff --git a/apps/playground-web/src/app/bridge/transaction-widget/TransactionPlayground.tsx b/apps/playground-web/src/app/bridge/transaction-widget/TransactionPlayground.tsx
@@ -21,6 +21,8 @@ const defaultOptions: BridgeComponentsPlaygroundOptions = {
     currency: "USD",
     showThirdwebBranding: true,
     receiverAddress: undefined,
+    amountEditable: true,
+    tokenEditable: true,
   },
   theme: {
     darkColorOverrides: {},
diff --git a/apps/portal/src/app/bridge/buy-widget/iframe/page.mdx b/apps/portal/src/app/bridge/buy-widget/iframe/page.mdx
@@ -140,6 +140,33 @@ By default, the widget displays thirdweb branding at the bottom. You can hide th
 
 <IframeCodePreview src="https://thirdweb.com/bridge/buy-widget?showThirdwebBranding=false" />
 
+### Editability Options
+
+You can control whether users can edit certain fields in the widget.
+
+
+<Details summary="Token Selection">
+
+By default, users can change the token they want to purchase.
+
+You can disable this by setting the `tokenEditable` query parameter to `false`.
+
+<IframeCodePreview src="https://thirdweb.com/bridge/buy-widget?chain=8453&tokenEditable=false" />
+
+</Details>
+
+<Details summary="Token Amount">
+
+By default, users can edit the purchase amount.
+
+You can disable this by setting the `amountEditable` query parameter to `false`.
+
+
+<IframeCodePreview src="https://thirdweb.com/bridge/buy-widget?chain=8453&amount=0.01&amountEditable=false" />
+
+</Details>
+
+
 ## Listening for Events
 
 The buy widget iframe sends events to the parent window using `postMessage` when a purchase succeeds or fails.
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/BuyWidget.tsx b/packages/thirdweb/src/react/web/ui/Bridge/BuyWidget.tsx
@@ -213,6 +213,16 @@ export type BuyWidgetProps = {
    * Callback to be called when the user disconnects the active wallet.
    */
   onDisconnect?: () => void;
+
+  /**
+   * By default the token amount is editable. Set this to false to disable editing the token amount
+   */
+  amountEditable?: boolean;
+
+  /**
+   * By default the token selection is editable. Set this to false to disable editing the token selection.
+   */
+  tokenEditable?: boolean;
 };
 
 /**
@@ -490,6 +500,12 @@ function BridgeWidgetContent(
     };
   });
 
+  const amountEditable =
+    props.amountEditable === undefined ? true : props.amountEditable;
+
+  const tokenEditable =
+    props.tokenEditable === undefined ? true : props.tokenEditable;
+
   if (screen.id === "1:buy-ui") {
     return (
       <FundWallet
@@ -525,6 +541,8 @@ function BridgeWidgetContent(
         setSelectedToken={setSelectedToken}
         amountSelection={amountSelection}
         setAmountSelection={setAmountSelection}
+        amountEditable={amountEditable}
+        tokenEditable={tokenEditable}
       />
     );
   }
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/FundWallet.tsx b/packages/thirdweb/src/react/web/ui/Bridge/FundWallet.tsx
@@ -113,6 +113,16 @@ type FundWalletProps = {
     description: string | undefined;
     image: string | undefined;
   };
+
+  /**
+   * Whether the user can edit the amount. Defaults to true.
+   */
+  amountEditable: boolean;
+
+  /**
+   * Whether the user can edit the token selection. Defaults to true.
+   */
+  tokenEditable: boolean;
 };
 
 export type SelectedToken =
@@ -264,6 +274,8 @@ export function FundWallet(props: FundWalletProps) {
             setDetailsModalOpen(true);
           }}
           currency={props.currency}
+          amountEditable={props.amountEditable}
+          tokenEditable={props.tokenEditable}
         />
 
         {receiver && isReceiverDifferentFromActiveWallet && (
@@ -415,6 +427,8 @@ function TokenSection(props: {
   };
   onWalletClick: () => void;
   presetOptions: [number, number, number];
+  amountEditable: boolean;
+  tokenEditable: boolean;
 }) {
   const theme = useCustomTheme();
   const chainQuery = useBridgeChain({
@@ -467,6 +481,7 @@ function TokenSection(props: {
         client={props.client}
         onSelectToken={props.onSelectToken}
         chain={chain}
+        disabled={props.tokenEditable === false}
       />
 
       <Container px="md" py="md">
@@ -479,6 +494,7 @@ function TokenSection(props: {
               value,
             });
           }}
+          disabled={props.amountEditable === false}
           style={{
             border: "none",
             boxShadow: "none",
@@ -527,6 +543,7 @@ function TokenSection(props: {
                   value,
                 });
               }}
+              disabled={props.amountEditable === false}
               style={{
                 border: "none",
                 boxShadow: "none",
@@ -541,36 +558,41 @@ function TokenSection(props: {
           )}
         </div>
 
-        <Spacer y="md" />
-
         {/* suggested amounts */}
-        <Container flex="row" gap="xxs">
-          {props.presetOptions.map((amount) => (
-            <Button
-              disabled={!props.selectedToken?.data}
-              key={amount}
-              onClick={() =>
-                props.setAmount({
-                  type: "usd",
-                  value: String(amount),
-                })
-              }
-              style={{
-                backgroundColor: "transparent",
-                color: theme.colors.secondaryText,
-                fontSize: fontSize.xs,
-                fontWeight: 400,
-                borderRadius: radius.full,
-                gap: "0.5px",
-                padding: `${spacing.xxs} ${spacing.sm}`,
-              }}
-              variant="outline"
-            >
-              <span>{getFiatSymbol(props.currency)}</span>
-              <span>{amount}</span>
-            </Button>
-          ))}
-        </Container>
+        {props.amountEditable && (
+          <>
+            <Spacer y="md" />
+            <Container flex="row" gap="xxs">
+              {props.presetOptions.map((amount) => (
+                <Button
+                  disabled={
+                    !props.selectedToken?.data || props.amountEditable === false
+                  }
+                  key={amount}
+                  onClick={() =>
+                    props.setAmount({
+                      type: "usd",
+                      value: String(amount),
+                    })
+                  }
+                  style={{
+                    backgroundColor: "transparent",
+                    color: theme.colors.secondaryText,
+                    fontSize: fontSize.xs,
+                    fontWeight: 400,
+                    borderRadius: radius.full,
+                    gap: "0.5px",
+                    padding: `${spacing.xxs} ${spacing.sm}`,
+                  }}
+                  variant="outline"
+                >
+                  <span>{getFiatSymbol(props.currency)}</span>
+                  <span>{amount}</span>
+                </Button>
+              ))}
+            </Container>
+          </>
+        )}
       </Container>
 
       {/* balance */}
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/common/selected-token-button.tsx b/packages/thirdweb/src/react/web/ui/Bridge/common/selected-token-button.tsx
diff --git a/packages/thirdweb/src/react/web/ui/components/buttons.tsx b/packages/thirdweb/src/react/web/ui/components/buttons.tsx
diff --git a/packages/thirdweb/src/stories/BuyWidget.stories.tsx b/packages/thirdweb/src/stories/BuyWidget.stories.tsx

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"thirdweb": patch
 +---
++
 +Add `amountEditable` and `tokenEditable` props on `BuyWidget` component to disable token selection and token amount editing
Original file line number	Diff line number	Diff line change
`@@ -68,5 +68,14 @@ export function buildBuyIframeUrl(options: BridgeComponentsPlaygroundOptions) {`
`68`	`68`	`);`
`69`	`69`	`}`
`70`	`70`
	`71`	`+ // Editability options`
	`72`	`+ if (options.payOptions.amountEditable === false) {`
	`73`	`+ url.searchParams.set("amountEditable", "false");`
	`74`	`+ }`
	`75`	`+`
	`76`	`+ if (options.payOptions.tokenEditable === false) {`
	`77`	`+ url.searchParams.set("tokenEditable", "false");`
	`78`	`+ }`
	`79`	`+`
`71`	`80`	`return url.toString();`
`72`	`81`	`}`