Lightning Out (Beta) Markup

We recommend using Lightning Out 2.0 instead of Lightning Out (beta). Lightning Out 2.0 is a new generally available feature that completely replaces–and isn’t an extension of–Lightning Out (beta), which is still subject to Beta Service Terms. See How Lightning Out 2.0 Compares to Lightning Out (Beta).

Tip

To use Lightning Out (beta) with your external app or page, first add the Lightning Out (beta) Javascript library to the page. Then, load your Lightning Out (beta) app with the $Lightning.use() function. Finally, to insert a Lightning web component into the page, call $Lightning.createComponent() from the callback function defined in $Lightning.use().

For example, here’s the markup for an external page that contains a custom Lightning web component. The page is available to guest users, so an authToken isn’t included as an argument in $Lightning.use().

1<html lang="en">
2    <head>
3        <meta charset="utf-8" />
4        <meta name="viewport" content="width=device-width, initial-scale=1" />
5    </head>
6    <body>
7        <h1>My External Page</h1>
8        <div id="lightning-out"></div>
9        <script src="https://SITE_DOMAIN/SITE_URL/lightning/lightning.out.js"></script>
10        <script>
11            $Lightning.use(
12                'c:MyLightningOutApp', // name of the Lightning Out (beta) app
13                function () { // callback after the framework and app load
14                    $Lightning.createComponent(
15                        'c:MyCustomComponent', // top-level component of the Lightning Out (beta) app
16                        {}, // attributes to set on the component
17                        'lightning-out', // DOM element ID where the component is inserted
18                        function (cmp) { // callback after the component loads
19                            console.log('The component was created.');
20                        }
21                    );
22                },
23                'https://SITE_DOMAIN/SITE_URL' // Experience Cloud site endpoint
24            );
25        </script>
26    </body>
27</html>

Add the Lightning Out (Beta) Library to the Page

To enable an origin server for use with Lightning Out (beta), include the Lightning Out (beta) JavaScript library in the app or page that hosts your Lightning Out (beta) app. Including the library requires a single line of markup.

1<script src="https://MY_DOMAIN_NAME.my.salesforce.com/lightning/lightning.out.js"></script>

If you plan to use Lightning Out (beta) with an Experience Cloud site, use your site endpoint URL instead.

1<script src="https://SITE_DOMAIN/SITE_URL/lightning/lightning.out.js"></script>

The Salesforce instance from which you load the Lightning Out (beta) Javascript library must match the instance specified in the lightningEndPointURI parameter of the $Lightning.use() function.

Important

Load and Initialize Your Lightning Out (Beta) App

Within another <script> tag, add the $Lightning.use() function. This function loads and initializes the Lightning Component framework for your Lightning Out (beta) app.

The $Lightning.use() function takes four arguments.

Name	Type	Description
`appName`	string	Required. The name of your Lightning Out (beta) app, including the namespace. For example, `"c:expenseAppDependencies"`.
`callback`	function	Required. A function to call after the Lightning Component framework and your app have fully loaded. The callback receives no arguments. Call `$Lightning.createComponent()` from this callback function.
`lightningEndPointURI`	string	Required. The URL for the Lightning or Experience Cloud site domain on your Salesforce instance. For example, `https://myDomainName.lightning.force.com`.
`authToken`	string	Required. This argument is optional if you share the Lightning Out (beta) app with unauthenticated users. The session ID or OAuth access token for a valid, active Salesforce session. You must obtain this token in your own code. Lightning Out (beta) doesn’t handle authentication for you. See Authentication from Lightning Out (Beta).

You can’t use more than one Lightning Out (beta) app on a page. You can call $Lightning.use() more than one time, but you must reference the same Lightning Out (beta) app in every call.

Note

Add Your Lightning Web Components to the Page

Add your components to the page with the $Lightning.createComponent() function. Call $Lightning.createComponent() from the callback function declared in $Lightning.use().

The $Lightning.createComponent() function takes four arguments.

Name	Type	Description
`componentName`	string	Required. The name of the Lightning web component to add to the page, including the namespace. For example, `"c:newExpenseForm"`.
`attributes`	Object	Required. The attributes to set on the component when it’s created. For example, `{ name: theName, amount: theAmount }`. If the component doesn’t require any attributes, pass in an empty object, `{ }`.
`domLocator`	Element or string	Required. The DOM element or element ID that indicates where on the page to insert the created component.
`callback`	function	A function to call after the component is added to and active on the page. The callback receives the component created as its only argument.

You can add more than one Lightning web component to a page. Within the callback function specified in $Lightning.use(), call $Lightning.createComponent() multiple times. To add the components to different parts of the page, use different DOM locators. You must specify each component in your Lightning Out (beta) app by using the <aura:dependency> tag.

Note

Behind the scenes, $Lightning.createComponent() calls the standard Aura $A.createComponent() function. Except for the DOM locator, the arguments are the same. And except for wrapping the call in some Lightning Out (beta) semantics, the behavior is also the same.

See Also

Lightning Aura Components Developer Guide: Dynamically Creating Components