checkout

Customize the PayPal Checkout Button

PayPal Checkout offers several style options to customize the look and feel 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:

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.

PayPal Checkout Integration Demo

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 Checkout
  • locale: '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 Recommended
Default: small
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 Matches the width of the container element, with the height decided dynamically based on width. Minimum width is 100px, maximum width is 500px. responsive button

Set the style.height option to one of these values:

Value Dimensions Description Button
small 25 to 55 pixels Recommended
Default: small
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.
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: The installment feature is available only in these locales: en_MX, es_MX, en_BR, pt_BR
Set style.installmentperiod to set the number of payments during the installment period:
  • en_BR, pt_BR: 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
  • en_MX, es_MX: 3, 6, 9, 12

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
horizontal Buttons are stacked horizontally with a maximum of two buttons. Recommended when:
  • Placing buttons on a product page, next to the product.
  • Space on the page is limited.
  • Local payment options are already provided.
Default: horizontal
Note: In a horizontal layout, the PayPal Credit button is enabled by default.
Mobile
Venmo is available only on mobile in U.S. markets.
Web
Venmo does not display on desktop.
vertical Buttons are stacked vertically with a maximum of four buttons. Recommended when:
  • Presenting a dynamic list of local payment options on checkout and shopping cart pages.
  • Leveraging PayPal checkout as a full stack payments platform.
Note: These parameters are not supported with vertical:
  • style.size: small
  • style.branding
  • style.tagline
  • style.fundingicons
Mobile
Venmo is available only on mobile in U.S. markets.
Web
Venmo does not display on desktop.

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 settings for each payment method type are shown in the Default column:

Value Description Default
paypal.FUNDING.CREDIT Enable buyers to pay with PayPal Credit.
Note: paypal.FUNDING.CREDIT should be set to disallowed for merchants that fall into these categories:
  • Non-USD currency
  • Real Money Gaming
  • Existing PayPal Credit button integration
Enabled by default for US buyers.
paypal.FUNDING.CARD Allow buyers to pay with their credit or debit card (Visa, Mastercard, American Express, Discover, and so on). Enabled by default for all buyers.
paypal.FUNDING.ELV Allow German buyers to pay with their bank account using Elektronisches Lastschriftverfahren. Enabled by 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.

See also

Feedback