Skip to content

[SDK] Add buttonLabel prop to checkout widgets #7805

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
merged 4 commits into from
Aug 7, 2025
Merged

[SDK] Add buttonLabel prop to checkout widgets #7805

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a7223f9
Add buttonLabel option to customize action button text in Bridge UI
cursoragent Aug 6, 2025
a61b402
Add optional button label customization to payment components
cursoragent Aug 6, 2025
0e2c5d0
lint
joaquim-verges Aug 7, 2025
001326c
changeset
joaquim-verges Aug 7, 2025
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
5 changes: 5 additions & 0 deletions .changeset/upset-pears-unite.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"thirdweb": patch
---
Comment on lines +2 to +3
Copy link
Contributor

@coderabbitai coderabbitai bot Aug 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Use a minor bump, not patch, for new public functionality

Per SemVer, adding a new backwards-compatible feature (the buttonLabel prop) warrants a minor version increment. Reserving patch for bug fixes avoids under-signalling changes to downstream consumers.

-"thirdweb": patch
+"thirdweb": minor
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
"thirdweb": patch
---
"thirdweb": minor
---
🤖 Prompt for AI Agents 
In the .changeset/upset-pears-unite.md file at lines 2 to 3, change the version
bump type from "patch" to "minor" because the addition of the new public
`buttonLabel` prop is a backwards-compatible feature and should be reflected as
a minor version increment according to SemVer guidelines.


Add ability to override button label for all payment widgets
2 changes: 1 addition & 1 deletion apps/playground-web/src/app/payments/components/CodeGen.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
1 change: 1 addition & 0 deletions apps/playground-web/src/app/payments/components/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ export type BridgeComponentsPlaygroundOptions = {
title: string | undefined;
image: string | undefined;
description: string | undefined;
buttonLabel: string | undefined;

buyTokenAddress?: Address;
buyTokenAmount: string;
Expand Down
21 changes: 21 additions & 0 deletions apps/playground-web/src/app/payments/embed/LeftSection.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down Expand Up @@ -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>

Expand Down
9 changes: 9 additions & 0 deletions apps/playground-web/src/app/payments/embed/RightSection.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
})}
/>
);
}
Expand All @@ -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,
})}
/>
);
}
Expand All @@ -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,
})}
/>
);
}
Expand Down
1 change: 1 addition & 0 deletions apps/playground-web/src/app/payments/embed/page.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ const defaultConnectOptions: BridgeComponentsPlaygroundOptions = {
buyTokenChain: arbitrum,
description: "",
image: "",
buttonLabel: "",
paymentMethods: ["crypto", "card"],
sellerAddress: "0x0000000000000000000000000000000000000000",
title: "",
Expand Down
1 change: 1 addition & 0 deletions packages/thirdweb/src/react/web/ui/Bridge/BridgeOrchestrator.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ export type UIOptions = Prettify<
image?: string;
};
currency?: SupportedFiatCurrency;
buttonLabel?: string;
} & (
| {
mode: "fund_wallet";
Expand Down
8 changes: 8 additions & 0 deletions packages/thirdweb/src/react/web/ui/Bridge/BuyWidget.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,11 @@
* @default "USD"
*/
currency?: SupportedFiatCurrency;

/**
* Custom label for the main action button.
*/
buttonLabel?: string;
};

// Enhanced UIOptions to handle unsupported token state
Expand Down Expand Up @@ -335,6 +340,7 @@
},
mode: "fund_wallet",
currency: props.currency || "USD",
buttonLabel: props.buttonLabel,

Check warning on line 343 in packages/thirdweb/src/react/web/ui/Bridge/BuyWidget.tsx

View check run for this annotation

Codecov / codecov/patch

packages/thirdweb/src/react/web/ui/Bridge/BuyWidget.tsx#L343 

Added line #L343 was not covered by tests
},
type: "success",
};
Expand Down Expand Up @@ -364,6 +370,8 @@
title: props.title,
},
mode: "fund_wallet",
currency: props.currency || "USD",
buttonLabel: props.buttonLabel,

Check warning on line 374 in packages/thirdweb/src/react/web/ui/Bridge/BuyWidget.tsx

View check run for this annotation

Codecov / codecov/patch

packages/thirdweb/src/react/web/ui/Bridge/BuyWidget.tsx#L373-L374 

Added lines #L373 - L374 were not covered by tests
},
type: "success",
};
Expand Down
6 changes: 6 additions & 0 deletions packages/thirdweb/src/react/web/ui/Bridge/CheckoutWidget.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -186,6 +186,11 @@
* @default "USD"
*/
currency?: SupportedFiatCurrency;

/**
* Custom label for the main action button.
*/
buttonLabel?: string;
};

// Enhanced UIOptions to handle unsupported token state
Expand Down Expand Up @@ -310,6 +315,7 @@
},
mode: "direct_payment",
currency: props.currency || "USD",
buttonLabel: props.buttonLabel,

Check warning on line 318 in packages/thirdweb/src/react/web/ui/Bridge/CheckoutWidget.tsx

View check run for this annotation

Codecov / codecov/patch

packages/thirdweb/src/react/web/ui/Bridge/CheckoutWidget.tsx#L318 

Added line #L318 was not covered by tests
paymentInfo: {
amount: props.amount,
feePayer: props.feePayer === "seller" ? "receiver" : "sender",
Expand Down
6 changes: 5 additions & 1 deletion packages/thirdweb/src/react/web/ui/Bridge/DirectPayment.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,11 @@
);
};

const buyNow = (
const buyNow = uiOptions.buttonLabel ? (
<Text color="primaryButtonText" size="md">
{uiOptions.buttonLabel}
</Text>

Check warning on line 70 in packages/thirdweb/src/react/web/ui/Bridge/DirectPayment.tsx

View check run for this annotation

Codecov / codecov/patch

packages/thirdweb/src/react/web/ui/Bridge/DirectPayment.tsx#L67-L70 

Added lines #L67 - L70 were not covered by tests
) : (
<Container flex="row" gap="3xs">
<Text color="primaryButtonText" size="md">
Buy Now ·
Expand Down
7 changes: 5 additions & 2 deletions packages/thirdweb/src/react/web/ui/Bridge/FundWallet.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -336,13 +336,16 @@
}}
variant="primary"
>
Buy {amount} {uiOptions.destinationToken.symbol}
{uiOptions.buttonLabel ||
`Buy ${amount} ${uiOptions.destinationToken.symbol}`}

Check warning on line 340 in packages/thirdweb/src/react/web/ui/Bridge/FundWallet.tsx

View check run for this annotation

Codecov / codecov/patch

packages/thirdweb/src/react/web/ui/Bridge/FundWallet.tsx#L339-L340 

Added lines #L339 - L340 were not covered by tests
</Button>
) : (
<ConnectButton
client={client}
connectButton={{
label: `Buy ${amount} ${uiOptions.destinationToken.symbol}`,
label:
uiOptions.buttonLabel ||
`Buy ${amount} ${uiOptions.destinationToken.symbol}`,

Check warning on line 348 in packages/thirdweb/src/react/web/ui/Bridge/FundWallet.tsx

View check run for this annotation

Codecov / codecov/patch

packages/thirdweb/src/react/web/ui/Bridge/FundWallet.tsx#L346-L348 

Added lines #L346 - L348 were not covered by tests
}}
theme={theme}
{...connectOptions}
Expand Down
2 changes: 1 addition & 1 deletion packages/thirdweb/src/react/web/ui/Bridge/TransactionPayment.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@
transactionDataQuery.data?.functionInfo?.functionName || "Contract Call";
const isLoading = transactionDataQuery.isLoading || chainMetadata.isLoading;

const buttonLabel = `Execute ${functionName}`;
const buttonLabel = uiOptions.buttonLabel || `Execute ${functionName}`;

Check warning on line 115 in packages/thirdweb/src/react/web/ui/Bridge/TransactionPayment.tsx

View check run for this annotation

Codecov / codecov/patch

packages/thirdweb/src/react/web/ui/Bridge/TransactionPayment.tsx#L115 

Added line #L115 was not covered by tests

if (isLoading) {
return (
Expand Down
6 changes: 6 additions & 0 deletions packages/thirdweb/src/react/web/ui/Bridge/TransactionWidget.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,11 @@
* @default "USD"
*/
currency?: SupportedFiatCurrency;

/**
* Custom label for the main action button.
*/
buttonLabel?: string;
};

// Enhanced UIOptions to handle unsupported token state
Expand Down Expand Up @@ -349,6 +354,7 @@
return {
data: {
currency: props.currency || "USD",
buttonLabel: props.buttonLabel,

Check warning on line 357 in packages/thirdweb/src/react/web/ui/Bridge/TransactionWidget.tsx

View check run for this annotation

Codecov / codecov/patch

packages/thirdweb/src/react/web/ui/Bridge/TransactionWidget.tsx#L357 

Added line #L357 was not covered by tests
metadata: {
description: props.description,
image: props.image,
Expand Down
31 changes: 31 additions & 0 deletions packages/thirdweb/src/stories/Bridge/DirectPayment.stories.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'.",
},
},
},
};
31 changes: 31 additions & 0 deletions packages/thirdweb/src/stories/Bridge/FundWallet.stories.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'.",
},
},
},
};
31 changes: 31 additions & 0 deletions packages/thirdweb/src/stories/Bridge/TransactionPayment.stories.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'.",
},
},
},
};
45 changes: 42 additions & 3 deletions packages/thirdweb/src/stories/Bridge/fixtures.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: {
Expand Down Expand Up @@ -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: {
Expand Down Expand Up @@ -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: {
Expand All @@ -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,
},
};
Loading