Use Third-Party JavaScript Libraries

Before you use a third-party JavaScript library, we recommend that you check AppExchange for third-party apps that match your requirements. Alternatively, check if a base component provides your desired functionality.

You can use third-party JavaScript libraries with Lightning web components. For example, use a library with interactive charts and graphs or a library that reduces code complexity.

  1. Download the library from the third-party library's site.

  2. Upload the library to your Salesforce organization as a static resource, which is a Lightning Web Components content security policy requirement.

  3. In a JavaScript class that extends LightningElement:

  4. Load the library and call its functions in a then() method.

If your component runs in an org where Lightning Web Security (LWS) isn’t enabled, libraries that are used by your component must meet Lightning Locker requirements. See Determine Whether a JavaScript Library Is Locker Compliant. If the org is using Lightning Web Security (LWS), most third-party libraries work as expected without changes. However, some libraries require changes to work with LWS. See Third-Party Library Considerations for LWS.

Using JavaScript to manipulate the DOM isn’t recommended because the Lightning Web Components engine does it more efficiently. However, there are some third-party JavaScript libraries that take over the DOM.

Salesforce doesn't provide support for third-party JavaScript libraries. Documentation and examples that demonstrate using a third-party JavaScript library don't constitute an endorsement of the third-party JavaScript library. We recommend that you check the third-party JavaScript library documentation for usage information.

If a call to appendChild() manipulates the DOM, styling isn’t applied to the appended element.

When using these libraries in a Lightning web component, add lwc:dom="manual" to any HTML element that you want to manipulate with JavaScript. When the engine sees the directive, it preserves encapsulation.

Add the lwc:dom="manual" directive to an empty native HTML element. The owner of the component calls appendChild() on that element to manually insert the DOM.

This example uses the D3 JavaScript library to create an interactive data visualization.

You can follow the example using the libsD3 component from the lwc-recipes repo. If you had deployed lwc-recipes in your org previously, you can skip the first 2 steps. Verify that the d3 JavaScript library is available in the Static Resources page of your Salesforce org.

A component displaying a graph of colored dots connected by lines. You can click and drag the dots to change the shape of the graph.

To use the library:

  1. Download the D3 JavaScript library at the lwc-recipes repo. At the time of writing, the example uses v5.16.0 of the D3 JavaScript Library.

  2. Compress the JavaScript and CSS files into a zip file. Name the file d3.zip. Upload d3.zip to your org as a static resource.

  3. Create a component to contain the graph. Here, the container is an empty <svg>. The lwc:dom="manual" directive tells LWC that the DOM in the <svg> element has been inserted manually.

In the component’s JavaScript class, import loadStyle and loadScript from lightning/platformResourceLoader. Import the d3 static resource as well. Notice that D3 is the static resource reference for loading the resources, and d3 is the name of the static resource uploaded to Salesforce.

To create the graph, invoke loadStyle and loadScript in renderedCallback() on the first render. Using renderedCallback() ensures that the page loads and renders the container before the graph is created.

Calls to loadStyle and loadScript return promises. Use Promise.all() to aggregate the results and ensure that both files are resolved before invoking the callback. The then() callback is invoked only after the load completes and only if no error occurs. To handle any potential error occurring during the load process, you can provide a catch() callback.

To initialize the graph in the promise callback, call initializeD3(), which reaches into the DOM and gets a reference to the container that displays the graph, here an <svg> element.

In a Lightning web component, you can’t use document to query for DOM elements. Instead, use this.template. For example, this D3 code sample uses this.template.querySelector('svg.d3'). See DOM Access Containment.

Here are some useful patterns for loading your code. This code loads a JavaScript library without a CSS file.

This code loads multiple JavaScript files in parallel.

See Also