[SDK] Add buttonLabel prop to checkout widgets (#7805)

joaquim-verges · cursoragent · web-flow · commit 621c1de62e48 · 2025-08-06T18:23:53.000-07:00
Co-authored-by: Cursor Agent &lt;cursoragent@cursor.com&gt;
diff --git a/.changeset/upset-pears-unite.md b/.changeset/upset-pears-unite.md
@@ -0,0 +1,5 @@
+---
+"thirdweb": patch
+---
+
+Add ability to override button label for all payment widgets
diff --git a/apps/playground-web/src/app/payments/components/CodeGen.tsx b/apps/playground-web/src/app/payments/components/CodeGen.tsx
@@ -71,7 +71,7 @@ function Example() {
     <${componentName}
       client={client}
       chain={defineChain(${options.payOptions.buyTokenChain.id})}
-      amount="${options.payOptions.buyTokenAmount}"${options.payOptions.buyTokenAddress ? `\n\t  tokenAddress="${options.payOptions.buyTokenAddress}"` : ""}${options.payOptions.sellerAddress ? `\n\t  seller="${options.payOptions.sellerAddress}"` : ""}${options.payOptions.title ? `\n\t  ${options.payOptions.widget === "checkout" ? "name" : "title"}="${options.payOptions.title}"` : ""}${options.payOptions.image ? `\n\t  image="${options.payOptions.image}"` : ""}${options.payOptions.description ? `\n\t  description="${options.payOptions.description}"` : ""}${options.payOptions.paymentMethods && options.payOptions.paymentMethods.length > 0 ? `\n\t  paymentMethods={${JSON.stringify(options.payOptions.paymentMethods)}}` : ""}${options.payOptions.currency ? `\n\t  currency="${options.payOptions.currency}"` : ""}${
+      amount="${options.payOptions.buyTokenAmount}"${options.payOptions.buyTokenAddress ? `\n\t  tokenAddress="${options.payOptions.buyTokenAddress}"` : ""}${options.payOptions.sellerAddress ? `\n\t  seller="${options.payOptions.sellerAddress}"` : ""}${options.payOptions.title ? `\n\t  ${options.payOptions.widget === "checkout" ? "name" : "title"}="${options.payOptions.title}"` : ""}${options.payOptions.image ? `\n\t  image="${options.payOptions.image}"` : ""}${options.payOptions.description ? `\n\t  description="${options.payOptions.description}"` : ""}${options.payOptions.buttonLabel ? `\n\t  buttonLabel="${options.payOptions.buttonLabel}"` : ""}${options.payOptions.paymentMethods && options.payOptions.paymentMethods.length > 0 ? `\n\t  paymentMethods={${JSON.stringify(options.payOptions.paymentMethods)}}` : ""}${options.payOptions.currency ? `\n\t  currency="${options.payOptions.currency}"` : ""}${
         options.payOptions.widget === "transaction"
           ? `\n\t  transaction={claimTo({
         contract: nftContract,
diff --git a/apps/playground-web/src/app/payments/components/types.ts b/apps/playground-web/src/app/payments/components/types.ts
@@ -41,6 +41,7 @@ export type BridgeComponentsPlaygroundOptions = {
     title: string | undefined;
     image: string | undefined;
     description: string | undefined;
+    buttonLabel: string | undefined;
 
     buyTokenAddress?: Address;
     buyTokenAmount: string;
diff --git a/apps/playground-web/src/app/payments/embed/LeftSection.tsx b/apps/playground-web/src/app/payments/embed/LeftSection.tsx
@@ -73,6 +73,7 @@ export function LeftSection(props: {
   const modalTitleId = useId();
   const modalTitleIconId = useId();
   const modalDescriptionId = useId();
+  const buttonLabelId = useId();
   const themeId = useId();
   const cryptoPaymentId = useId();
   const cardPaymentId = useId();
@@ -486,6 +487,26 @@ export function LeftSection(props: {
               value={options.payOptions.description}
             />
           </div>
+
+          {/* Button Label */}
+          <div className="flex flex-col gap-2">
+            <Label htmlFor={buttonLabelId}>Button Label</Label>
+            <Input
+              className="bg-card"
+              id={buttonLabelId}
+              onChange={(e) =>
+                setOptions((v) => ({
+                  ...v,
+                  payOptions: {
+                    ...payOptions,
+                    buttonLabel: e.target.value,
+                  },
+                }))
+              }
+              placeholder="Custom button text (optional)"
+              value={options.payOptions.buttonLabel}
+            />
+          </div>
         </div>
       </CollapsibleSection>
 
diff --git a/apps/playground-web/src/app/payments/embed/RightSection.tsx b/apps/playground-web/src/app/payments/embed/RightSection.tsx
@@ -66,6 +66,9 @@ export function RightSection(props: {
         tokenAddress={props.options.payOptions.buyTokenAddress}
         currency={props.options.payOptions.currency}
         showThirdwebBranding={props.options.payOptions.showThirdwebBranding}
+        {...(props.options.payOptions.buttonLabel && {
+          buttonLabel: props.options.payOptions.buttonLabel,
+        })}
       />
     );
   }
@@ -91,6 +94,9 @@ export function RightSection(props: {
         tokenAddress={props.options.payOptions.buyTokenAddress}
         currency={props.options.payOptions.currency}
         showThirdwebBranding={props.options.payOptions.showThirdwebBranding}
+        {...(props.options.payOptions.buttonLabel && {
+          buttonLabel: props.options.payOptions.buttonLabel,
+        })}
       />
     );
   }
@@ -112,6 +118,9 @@ export function RightSection(props: {
         })}
         currency={props.options.payOptions.currency}
         showThirdwebBranding={props.options.payOptions.showThirdwebBranding}
+        {...(props.options.payOptions.buttonLabel && {
+          buttonLabel: props.options.payOptions.buttonLabel,
+        })}
       />
     );
   }
diff --git a/apps/playground-web/src/app/payments/embed/page.tsx b/apps/playground-web/src/app/payments/embed/page.tsx
@@ -13,6 +13,7 @@ const defaultConnectOptions: BridgeComponentsPlaygroundOptions = {
     buyTokenChain: arbitrum,
     description: "",
     image: "",
+    buttonLabel: "",
     paymentMethods: ["crypto", "card"],
     sellerAddress: "0x0000000000000000000000000000000000000000",
     title: "",
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/BridgeOrchestrator.tsx b/packages/thirdweb/src/react/web/ui/Bridge/BridgeOrchestrator.tsx
@@ -42,6 +42,7 @@ export type UIOptions = Prettify<
       image?: string;
     };
     currency?: SupportedFiatCurrency;
+    buttonLabel?: string;
   } & (
     | {
         mode: "fund_wallet";
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/BuyWidget.tsx b/packages/thirdweb/src/react/web/ui/Bridge/BuyWidget.tsx
@@ -180,6 +180,11 @@ export type BuyWidgetProps = {
    * @default "USD"
    */
   currency?: SupportedFiatCurrency;
+
+  /**
+   * Custom label for the main action button.
+   */
+  buttonLabel?: string;
 };
 
 // Enhanced UIOptions to handle unsupported token state
@@ -335,6 +340,7 @@ export function BuyWidget(props: BuyWidgetProps) {
             },
             mode: "fund_wallet",
             currency: props.currency || "USD",
+            buttonLabel: props.buttonLabel,
           },
           type: "success",
         };
@@ -364,6 +370,8 @@ export function BuyWidget(props: BuyWidgetProps) {
             title: props.title,
           },
           mode: "fund_wallet",
+          currency: props.currency || "USD",
+          buttonLabel: props.buttonLabel,
         },
         type: "success",
       };
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/CheckoutWidget.tsx b/packages/thirdweb/src/react/web/ui/Bridge/CheckoutWidget.tsx
@@ -186,6 +186,11 @@ export type CheckoutWidgetProps = {
    * @default "USD"
    */
   currency?: SupportedFiatCurrency;
+
+  /**
+   * Custom label for the main action button.
+   */
+  buttonLabel?: string;
 };
 
 // Enhanced UIOptions to handle unsupported token state
@@ -310,6 +315,7 @@ export function CheckoutWidget(props: CheckoutWidgetProps) {
           },
           mode: "direct_payment",
           currency: props.currency || "USD",
+          buttonLabel: props.buttonLabel,
           paymentInfo: {
             amount: props.amount,
             feePayer: props.feePayer === "seller" ? "receiver" : "sender",
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/DirectPayment.tsx b/packages/thirdweb/src/react/web/ui/Bridge/DirectPayment.tsx
@@ -64,7 +64,11 @@ export function DirectPayment({
     );
   };
 
-  const buyNow = (
+  const buyNow = uiOptions.buttonLabel ? (
+    <Text color="primaryButtonText" size="md">
+      {uiOptions.buttonLabel}
+    </Text>
+  ) : (
     <Container flex="row" gap="3xs">
       <Text color="primaryButtonText" size="md">
         Buy Now ·
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/FundWallet.tsx b/packages/thirdweb/src/react/web/ui/Bridge/FundWallet.tsx
@@ -336,13 +336,16 @@ export function FundWallet({
           }}
           variant="primary"
         >
-          Buy {amount} {uiOptions.destinationToken.symbol}
+          {uiOptions.buttonLabel ||
+            `Buy ${amount} ${uiOptions.destinationToken.symbol}`}
         </Button>
       ) : (
         <ConnectButton
           client={client}
           connectButton={{
-            label: `Buy ${amount} ${uiOptions.destinationToken.symbol}`,
+            label:
+              uiOptions.buttonLabel ||
+              `Buy ${amount} ${uiOptions.destinationToken.symbol}`,
           }}
           theme={theme}
           {...connectOptions}
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/TransactionPayment.tsx b/packages/thirdweb/src/react/web/ui/Bridge/TransactionPayment.tsx
@@ -112,7 +112,7 @@ export function TransactionPayment({
     transactionDataQuery.data?.functionInfo?.functionName || "Contract Call";
   const isLoading = transactionDataQuery.isLoading || chainMetadata.isLoading;
 
-  const buttonLabel = `Execute ${functionName}`;
+  const buttonLabel = uiOptions.buttonLabel || `Execute ${functionName}`;
 
   if (isLoading) {
     return (
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/TransactionWidget.tsx b/packages/thirdweb/src/react/web/ui/Bridge/TransactionWidget.tsx
@@ -189,6 +189,11 @@ export type TransactionWidgetProps = {
    * @default "USD"
    */
   currency?: SupportedFiatCurrency;
+
+  /**
+   * Custom label for the main action button.
+   */
+  buttonLabel?: string;
 };
 
 // Enhanced UIOptions to handle unsupported token state
@@ -349,6 +354,7 @@ export function TransactionWidget(props: TransactionWidgetProps) {
       return {
         data: {
           currency: props.currency || "USD",
+          buttonLabel: props.buttonLabel,
           metadata: {
             description: props.description,
             image: props.image,
diff --git a/packages/thirdweb/src/stories/Bridge/DirectPayment.stories.tsx b/packages/thirdweb/src/stories/Bridge/DirectPayment.stories.tsx
@@ -223,3 +223,34 @@ export const NoImageLight: Story = {
     },
   },
 };
+
+export const CustomButtonLabel: Story = {
+  args: {
+    theme: "dark",
+    uiOptions: DIRECT_PAYMENT_UI_OPTIONS.customButton,
+  },
+  parameters: {
+    backgrounds: { default: "dark" },
+    docs: {
+      description: {
+        story:
+          "Example showcasing custom button label functionality. The button shows 'Purchase Now' instead of the default 'Buy Now' text.",
+      },
+    },
+  },
+};
+
+export const CustomButtonLabelLight: Story = {
+  args: {
+    theme: "light",
+    uiOptions: DIRECT_PAYMENT_UI_OPTIONS.customButton,
+  },
+  parameters: {
+    backgrounds: { default: "light" },
+    docs: {
+      description: {
+        story: "Light theme version with custom button label 'Purchase Now'.",
+      },
+    },
+  },
+};
diff --git a/packages/thirdweb/src/stories/Bridge/FundWallet.stories.tsx b/packages/thirdweb/src/stories/Bridge/FundWallet.stories.tsx
@@ -194,3 +194,34 @@ export const LargeAmountLight: Story = {
     },
   },
 };
+
+export const CustomButtonLabel: Story = {
+  args: {
+    theme: "dark",
+    uiOptions: FUND_WALLET_UI_OPTIONS.customButton,
+  },
+  parameters: {
+    backgrounds: { default: "dark" },
+    docs: {
+      description: {
+        story:
+          "Example showcasing custom button label functionality. The button shows 'Add Funds Now' instead of the default 'Buy [amount] [symbol]' text.",
+      },
+    },
+  },
+};
+
+export const CustomButtonLabelLight: Story = {
+  args: {
+    theme: "light",
+    uiOptions: FUND_WALLET_UI_OPTIONS.customButton,
+  },
+  parameters: {
+    backgrounds: { default: "light" },
+    docs: {
+      description: {
+        story: "Light theme version with custom button label 'Add Funds Now'.",
+      },
+    },
+  },
+};
diff --git a/packages/thirdweb/src/stories/Bridge/TransactionPayment.stories.tsx b/packages/thirdweb/src/stories/Bridge/TransactionPayment.stories.tsx
@@ -168,3 +168,34 @@ export const ContractInteractionLight: Story = {
     },
   },
 };
+
+export const CustomButtonLabel: Story = {
+  args: {
+    theme: "dark",
+    uiOptions: TRANSACTION_UI_OPTIONS.customButton,
+  },
+  parameters: {
+    backgrounds: { default: "dark" },
+    docs: {
+      description: {
+        story:
+          "Example showcasing custom button label functionality. The button shows 'Execute Now' instead of the default 'Execute [functionName]' text.",
+      },
+    },
+  },
+};
+
+export const CustomButtonLabelLight: Story = {
+  args: {
+    theme: "light",
+    uiOptions: TRANSACTION_UI_OPTIONS.customButton,
+  },
+  parameters: {
+    backgrounds: { default: "light" },
+    docs: {
+      description: {
+        story: "Light theme version with custom button label 'Execute Now'.",
+      },
+    },
+  },
+};
diff --git a/packages/thirdweb/src/stories/Bridge/fixtures.ts b/packages/thirdweb/src/stories/Bridge/fixtures.ts
@@ -684,7 +684,7 @@ type TransactionUIOptions = Extract<UIOptions, { mode: "transaction" }>;
 
 // UI Options for FundWallet mode
 export const FUND_WALLET_UI_OPTIONS: Record<
-  "ethDefault" | "ethWithAmount" | "usdcDefault" | "uniLarge",
+  "ethDefault" | "ethWithAmount" | "usdcDefault" | "uniLarge" | "customButton",
   FundWalletUIOptions
 > = {
   ethDefault: {
@@ -718,11 +718,26 @@ export const FUND_WALLET_UI_OPTIONS: Record<
     initialAmount: "5",
     mode: "fund_wallet" as const,
   },
+  customButton: {
+    destinationToken: ETH,
+    initialAmount: "0.01",
+    metadata: {
+      description: "Test custom button label for funding",
+      title: "Custom Fund Wallet",
+    },
+    mode: "fund_wallet" as const,
+    buttonLabel: "Add Funds Now",
+  },
 };
 
 // UI Options for DirectPayment mode
 export const DIRECT_PAYMENT_UI_OPTIONS: Record<
-  "digitalArt" | "concertTicket" | "subscription" | "sneakers" | "credits",
+  | "digitalArt"
+  | "concertTicket"
+  | "subscription"
+  | "sneakers"
+  | "credits"
+  | "customButton",
   DirectPaymentUIOptions
 > = {
   concertTicket: {
@@ -794,11 +809,26 @@ export const DIRECT_PAYMENT_UI_OPTIONS: Record<
       token: USDC,
     },
   },
+  customButton: {
+    metadata: {
+      description: "Test custom button label functionality",
+      image: PRODUCT_METADATA.digitalArt.image,
+      title: "Custom Button Test",
+    },
+    mode: "direct_payment" as const,
+    buttonLabel: "Purchase Now",
+    paymentInfo: {
+      amount: "0.05",
+      feePayer: "sender" as const,
+      sellerAddress: RECEIVER_ADDRESSES.primary,
+      token: ETH,
+    },
+  },
 };
 
 // UI Options for Transaction mode
 export const TRANSACTION_UI_OPTIONS: Record<
-  "ethTransfer" | "erc20Transfer" | "contractInteraction",
+  "ethTransfer" | "erc20Transfer" | "contractInteraction" | "customButton",
   TransactionUIOptions
 > = {
   contractInteraction: {
@@ -825,4 +855,13 @@ export const TRANSACTION_UI_OPTIONS: Record<
     mode: "transaction" as const,
     transaction: ethTransferTransaction,
   },
+  customButton: {
+    metadata: {
+      description: "Test custom button label for transactions",
+      title: "Custom Transaction",
+    },
+    mode: "transaction" as const,
+    buttonLabel: "Execute Now",
+    transaction: ethTransferTransaction,
+  },
 };

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"thirdweb": patch
 +---
++
 +Add ability to override button label for all payment widgets