Customize the PayPal button

Express Checkout offers several style options that you can use to customize the look and feel of your payment button. You can also take advantage of options that enable you to display multiple funding sources to the buyer, when appropriate.

These sections show you how to customize a checkout button:

Customization Example

This example shows the customization for the button language, size, color, and shape:

paypal.Button.render({

    env: 'production',

    locale: 'en_US',

    style: {
        size: 'small',
        color: 'gold',
        shape: 'pill',
        label: 'checkout'
    },

    // Pass all other options that the button requires here
});

To customize the button, use these parameters:

Parameter Value Type Description
env production String OPTIONAL
Default is the live production environment. For testing, set to sandbox. To go live after testing, remove this setting or change it to production.
locale Supported locales String OPTIONAL
The locale code of the country and language to display on the button. Default is en_US.
style Button Style Object OPTIONAL
Style options for the button.

Supported locales

To specify the button language, set locale to one of these supported locales: en_US, en_AU, en_GB, fr_CA, es_ES, it_IT, fr_FR, de_DE, pt_BR, zh_CN, da_DK, zh_HK, id_ID, he_IL, ja_JP, ko_KR, nl_NL, no_NO, pl_PL, pt_PT, ru_RU, sv_SE, th_TH, zh_TW.

For example:

  • locale: 'en_US' displays PayPal Check Out
  • 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 parameter to one of these values:

Value Description
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 alternate
If gold is not an option 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 Second alternate
If gold or blue do not work for your site design or aesthetic, try the silver button. Because this color is a bit recessive and less capable of drawing people’s attention, we recommend this button color as a second alternative.
black Third alternate
If your website demands a monochromatic button experience, 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 parameter to one of these values:

Value Description
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 parameter to one of these values:

Value Dimensions Description
small 150 pixels by 25 pixels Recommended
Default is 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, height is decided dynamically based on width. Minimum width is 150px, maximum width is 500px.

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% 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 is 100 pixels.

This example shows a responsive button with a media query. The button displays:

  • 100% 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: 250pixels;
        }
    }
</style>

<div id="paypal-button-container"></div>

<script>
    paypal.Button.render({
        style: { size:  'responsive' },
    }, '#paypal-button-container');
</script>

Label

Set the style.label parameter to one of these values:

Value Description
checkout The PayPal Checkout button. The default button.
credit The PayPal Credit button. Initializes the credit flow. Cannot be used with any custom color option.
pay The Pay With PayPal button. Initializes the checkout flow.
buynow The Buy Now button. Initializes the checkout flow. The default Buy Now button is unbranded. To include PayPal branding, set branding: true.
paypal The generic PayPal button. Initializes the checkout flow. This button contains only the PayPal brand logo.

Tagline

To disable the tagline/text beneath the button, set style.tagline to false.

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 parameter determines if the buttons are stacked horizontally (side-by-side) or vertically (top-to-bottom).

Set the style.layout parameter to determine the button layout when multiple buttons are available:

Value Description
horizontal Buttons are stacked horizontally with a maximum of two buttons. (Default)

Recommended when:

  • Placing buttons on a product page, next to the product.
  • Space on the page is limited.
  • Alternative payment options are already provided.
vertical Buttons are stacked vertically with a maximum of four buttons.

Recommended when:

  • Presenting a dynamic list of alternative and 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.label
  • style.branding
  • style.tagline
  • style.fundingicons

To limit the maximum number of buttons displayed, set style.maxbuttons to a number from 1 to 4.

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 parameter 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 Allow buyers to pay with PayPal Credit. The button will be displayed to eligible buyers.
Note: paypal.FUNDING.CREDIT should be set to disallowed for merchants that fall into any of the 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:

paypal.Button.render({

    funding: {
        allowed: [ paypal.FUNDING.CREDIT ]
    }

}, '#paypal-button-container');

This example opts-out of displaying the credit-card button:

paypal.Button.render({

    funding: {
        disallowed: [ paypal.FUNDING.CARD ]
    }

}, '#paypal-button-container');

Note: Adding a funding source to funding.allowed only shows the funding source to eligible buyers. For example, if you specify allowed: [ paypal.FUNDING.CREDIT ], the credit button is only shown to buyers in countries where PayPal Credit is offered.

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 parameter to one of these values:

Value Description
true Displays funding instrument icons. Not valid for the credit button.
false Hides funding instrument icons.

Interactive demo

To create and test your PayPal button, use the interactive demo. You can edit the code in the demo to try out different button styles and optional button features.

PayPal Express Checkout Integration Demo