Customize the PayPal Checkout Button
Important: PayPal supports these Checkout integrations:
- Smart Payment Buttons, which use the PayPal JavaScript SDK. Valid from February 2019 for new integrations.
- Checkout with
checkout.js
. Valid before February 2019. Customers who usecheckout.js
can access reference and support material in this Checkout guide. However, PayPal does not updatecheckout.js
with new features and enhancements.
PayPal Checkout offers several style options to customize the appearance and behavior of your smart payment button. You can also use options to display multiple funding sources to the buyer, when appropriate.
These topics describe how to customize your checkout button:
Customization example
This example shows customizations for the PayPal button's locale and style:
// Customize button (optional)
locale: 'en_US',
style: {
size: 'small',
color: 'gold',
shape: 'pill',
label: 'checkout',
tagline: 'true'
}
To customize the button, use these parameters:
Option | Value | Type | Description |
---|---|---|---|
locale |
Supported locales | String | OPTIONAL The locale code of the country and language to display on the button. Default: en_US |
style |
Button styles | Object | OPTIONAL Style options for the button, including color, shape, size, and label. |
Supported locales
To specify the button language, set locale
to a supported locale.
For example:
locale: 'en_US'
displays PayPal Checkoutlocale: 'de_DE'
displays PayPal Zur Kasse
Button styles
To define the color, shape, size, and label of the button, use the button style parameters. These guidelines recommend certain styles.
Color
Set the style.color
option to one of these values:
Value | Description | Button |
---|---|---|
gold |
Recommended People around the world know us for the color gold and research confirms it. Extensive testing determined just the right shade and shape that help increase conversion. Use it on your website to leverage PayPal’s recognition and preference. |
|
blue |
First alternative If gold does not work for your site, try the PayPal blue button. Research shows that people know it is our brand color, which provides a halo of trust and security to your experience. |
|
silver white |
Second alternatives If gold or blue does not work for your site design or aesthetic, try the silver or white buttons. Because these colors are a bit recessive and less capable of drawing people’s attention, we recommend these button colors as a second alternative. |
|
black |
Third alternative If your website demands a monochromatic button, try the black button. Because black is a common website color and less capable of drawing people's attention, we recommend this button as a third alternative. |
Shape
Set the style.shape
option to one of these values:
Value | Description | Button |
---|---|---|
pill |
Recommended Whenever possible, use the pill-shaped button. Its unique and powerful shape signifies PayPal in people’s minds. |
|
rect |
Use the rectangular button as an alternative for media such as mobile where pill-shaped buttons might pose design challenges. |
Size
Set the style.size
option to one of these values:
Value | Dimensions | Description | Button |
---|---|---|---|
small |
150 pixels by 25 pixels | Use to match the size of other small buttons on the page. | |
medium |
250 pixels by 35 pixels | Use to match the size of other medium buttons on the page. | |
large |
350 pixels by 40 pixels | Use to match the size of other large buttons on the page. | |
responsive |
Dynamic | Recommended Matches the width of the container element, with the height decided dynamically based on width. Minimum width is 100px , maximum width is 500px . |
Set the style.height
option to one of these values:
Value | Dimensions | Description | Button |
---|---|---|---|
small |
25 to 55 pixels | Use to match the height of other small buttons on the page. | |
medium |
35 to 55 pixels | Use to match the height of other medium buttons on the page. | |
large |
30 to 55 pixels | Use to match the height of other large buttons on the page. |
About responsive buttons
If you set style.size
to 'responsive'
, the button matches the width of the container element, and auto-calculates an appropriate height based on the width.
This example creates a button that is 200 pixels wide:
<div id="paypal-button" style="width: 200px"></div>
<script>
paypal.Button.render({
style: {
size: 'responsive'
}
});
</script>
This example creates a button that is 50 percent of the width of the parent element:
<div id="paypal-button" style="width: 50%"></div>
<script>
paypal.Button.render({
style: {
size: 'responsive'
}
}, '#paypal-button-container');
</script>
Note: The minimum width of the button for this example is
100
pixels.
This example code shows a responsive button with a media query. The button displays:
- 100 percent on mobile
- 250 pixels wide on a desktop
<style>
@media screen and (max-width: 400px) {
#paypal-button-container {
width: 100%;
}
}
@media screen and (min-width: 400px) {
#paypal-button-container {
width: 250px;
}
}
</style>
<div id="paypal-button-container"></div>
<script>
paypal.Button.render({
style: {
size: 'responsive'
}
}, '#paypal-button-container');
</script>
Label
Set the style.label
option to one of these values:
Value | Description | Button |
---|---|---|
checkout |
Displays the PayPal Checkout button. Default: checkout |
|
credit |
Displays the PayPal Credit button and initializes the credit flow. Cannot be used with any custom color option. (UK merchants) Credit is a regulated activity in the UK. Before integrating a PayPal Credit button, you must be authorized to act as a credit broker and have a credit agreement with PayPal. For more information, contact business customer support through paypal.com or by calling 0800 358 7929. |
|
pay |
Displays the Pay With PayPal button and initializes the checkout flow. | |
buynow |
Displays the Buy Now button and initializes the checkout flow. The default Buy Now button is unbranded. To include PayPal branding, set branding: true . |
|
paypal |
Displays the generic PayPal button and initializes the checkout flow. This button contains only the PayPal brand logo. | |
installment |
Displays the PayPal Installment button and offers a specified number of payments during a payment installment period. Note: TheSet style.installmentperiod to set the number of payments during the installment period:
|
Tagline
Set the style.tagline
to false
to disable the tagline text:
Value | Description | Button |
---|---|---|
true |
Display tagline text Default. |
|
false |
Disable tagline text. |
Multiple button layout
By default, PayPal shows a single button. However, if additional funding sources are available to the buyer through PayPal, such as Venmo, then multiple buttons are displayed in the space provided. The style.layout
option determines if the buttons are stacked horizontally (side-by-side) or vertically (top-to-bottom).
// Customize button (optional)
style: {
layout: 'horizontal',
fundingicons: 'true',
},
funding: {
allowed: [ paypal.FUNDING.CARD ],
disallowed: [ paypal.FUNDING.CREDIT ]
}
Layout
Set the style.layout
option to determine the button layout when multiple buttons are available:
Value | Description | Layout |
---|---|---|
vertical |
Default. Buttons are stacked vertically with a maximum of four buttons. Recommended when:
|
Venmo is available on mobile in U.S. markets only. PayPal Commerce Platform for Marketplaces and Platforms does not support Venmo. |
horizontal |
Buttons are stacked horizontally with a maximum of two buttons. Recommended when:
|
Venmo is available on mobile in U.S. markets only. PayPal Commerce Platform for Marketplaces and Platforms does not support Venmo. |
Funding methods
When multiple funding sources are available to the buyer, PayPal automatically determines which additional buttons are appropriate to display. However, you can choose to opt in or out of displaying specific funding sources in either the horizontal
or vertical
layout.
Set the funding
option to one of these values:
Value | Description |
---|---|
allowed |
Displays the specified funding methods, if the buyer is eligible. |
disallowed |
Hides the specified funding methods. |
Then, specify one or more of these funding sources.
The Default column shows the default settings for each payment method type:
Value | Description | Default |
---|---|---|
paypal.FUNDING.CREDIT |
Enable buyers to pay with PayPal Credit. Note: |
The default for U.S. buyers. |
paypal.FUNDING.CARD |
Allow buyers to pay with their credit or debit card (Visa, Mastercard, American Express, Discover, and so on). | The default for all buyers. |
paypal.FUNDING.VENMO |
Allow buyers to pay with Venmo. | The default for U.S. buyers. |
paypal.FUNDING.ELV |
Allow German buyers to pay with their bank account using Elektronisches Lastschriftverfahren. | The default for DE (German) buyers. |
This example opts in to PayPal Credit:
funding: {
allowed: [ paypal.FUNDING.CREDIT ]
}
Displays the PayPal Checkout and PayPal Credit buttons:
This example opts out of displaying the PayPal Credit button:
funding: {
disallowed: [ paypal.FUNDING.CREDIT ]
}
Note: When you add a funding source to
funding.allowed
, the funding source appears to eligible buyers. For example, if you set the following value, the credit button is shown only to buyers in countries where PayPal Credit is offered:allowed: [ paypal.FUNDING.CREDIT ]
Funding icons
When using the horizontal
layout, you can set style.fundingicons
to display or hide funding instrument icons beneath the payment button.
Set the style.fundingicons
option to one of these values:
Value | Description | Icons |
---|---|---|
true |
Displays funding instrument icons. Not valid for the credit button. |
|
false |
Hides funding instrument icons. |
Interactive code demo
To create and test your PayPal button, use the interactive code demo.
You can edit the code in the demo to try out different button styles and optional button features.
See also
- Customize the Checkout Flow
- PayPal Checkout Best Practices
- Advanced
checkout.js
docs in the PayPal Checkout GitHub repository