JavaScript SDK performance optimization

SDKCurrentLast updated: December 14th 2021, @ 1:27:59 pm

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:

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>

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>

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:
```

<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:

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);

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>

Load the SDK as a module

Loading the SDK as a module brings certain advantages, especially when working with single page applications. For example, you can optimize performance because the module lets you control loading behavior in JavaScript instead of HTML. It can also help reduce bugs by encapsulating data.

Use the paypal-js npm package to integrate with front-end build tools. This package follows best practices such as loading the script asynchronously and providing a promise interface to know when script loading is complete.
Use the react-paypal-js npm package within the React.js framework. It brings the same functionality as the paypal-js package, but tailored to the style of the framework. It ships React.js components for Buttons, Marks, and Messages on top.

See the projects' README.md documentation for further details.