JavaScript SDK performance optimization

Optimize loading the JavaScript SDK and rendering the payment buttons for the best performance.

Load the JavaScript SDK from the PayPal server

Load the JavaScript SDK from https://www.paypal.com/sdk/js only. Reasons include:

  • The script is dynamically bundled, based on your client ID and the current buyer. It includes only the specific code, images, localization, and other resources needed and does not slow down your page with unnecessary code. This approach is not possible with a statically-distributed script.
  • The script loads inside the button iframe and Checkout popup window to communicate with the parent window. Loading from paypal.com means your users' browsers cache the script and there is no need to download the script again inside the iframe or popup.
  • Security updates and bug fixes are instantly available to your users.
  • Conversion updates to drive extra sales and revenue through PayPal are instantly available.
  • Backwards compatibility with previous versions of the script.

Minified script

The script is minified by default. While you're developing, you can disable minified script, by adding debug=true to the script URL.

Instant render

If you are rendering the payment buttons immediately on the page after it loads, you should:

  1. Load the JavaScript SDK prior to the element you want to render into:

    <script src="https://www.paypal.com/sdk/js?client-id=CLIENT_ID"></script>
    
  2. Call paypal.Buttons().render('#container') as soon as possible when the container element is ready:

    <div id="paypal-button-container"></div>
    
    <script>
      paypal.Buttons().render('#paypal-button-container')
    </script>
    
  3. For a bonus performance boost, load the JavaScript SDK asynchronously on a page that precedes the checkout page. This approach pre-caches the script, making future loads and renders instantaneous:

    <!-- Place on one of your landing pages or pre-checkout pages -->
    <body>
      <script
        src="https://www.paypal.com/sdk/js?client-id=CLIENT_ID" async>
      </script>
    </body>
    

Delayed render

If your app renders on the client-side, or there is a user action on the page that triggers displaying the payment buttons (like opening a cart or selecting a radio button), you should:

  1. Load the JavaScript SDK asynchronously in your page:

    <head>
      <script src="https://www.paypal.com/sdk/js?client-id=CLIENT_ID"></script>
    </head>
    

    Alternatively, use JavaScript to asynchronously load the script:

      var PAYPAL_SCRIPT = 'https://www.paypal.com/sdk/js?client-id=CLIENT_ID';
      var script = document.createElement('script');
      script.setAttribute('src', PAYPAL_SCRIPT);
      document.head.appendChild(script);
    
  2. Call paypal.Buttons().render('#container') on the client-side render, route change, or user action that you want to trigger displaying the button:

    <div id="paypal-button-container"></div>
    
    <script>
       document.querySelector('#myRadioField')
         .addEventListener('click', function() {
           paypal.Buttons().render('#paypal-button-container')
         });
    </script>
    

    Alternatively, to ensure the button completely loads by the time it displays, render the button in advance in a hidden container, and display it on the page change or user action:

    <div id="paypal-button-container"></div>
    
    <script>
       document.querySelector('#paypal-button-container')
         .style.display = 'none';
    
       paypal.Buttons().render('#paypal-button-container');
    
       document.querySelector('#myRadioField')
         .addEventListener('click', function() {
           document.querySelector('#paypal-button-container')
             .style.display = 'block';
         });
    </script>
    

See also