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 use checkout.js can access reference and support material in this Checkout guide. However, PayPal does not update checkout.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
• Locales
• Button styles
• Multiple button layout
• Interactive code 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:

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:

Shape

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

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:

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:

Tagline

Set the style.tagline to false to disable the 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 the 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:

Then, specify one or more of these funding sources.

The Default column shows the default settings for each payment method type:

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:

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