Lightning Out Markup

Lightning Out requires some simple markup on the page, and is activated using two straightforward JavaScript functions.

The markup and JavaScript functions in the Lightning Out library are the only things specific to Lightning Out. Everything else is the Lightning web components code you already know and love.

Enable an origin server for use with Lightning Out by including the Lightning Out JavaScript library in the app or page hosting your standalone Aura dependency app. Including the library requires a single line of markup.

Use your custom domain for the host. Don’t copy-and-paste someone else’s instance from example source code. If you do this, your app will break whenever there’s a version mismatch between your Salesforce instance and the instance from which you’re loading the Lightning Out library. This happens at least three times a year, during regular upgrades of Salesforce. Don’t do it!

Load and initialize the Lightning Component framework and your standalone Aura dependency app with the $Lightning.use() function.

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

NameTypeDescription
appNamestringRequired. The name of your standalone Aura dependency app, including the namespace. For example, "c:expenseAppDependencies".
callbackfunctionA function to call once the Lightning Component framework and your app have fully loaded. The callback receives no arguments. This callback is usually where you call $Lightning.createComponent() to add your app to the page (see the next section). You might also update your display in other ways, or otherwise respond to your dependency app being ready.
lightningEndPointURIstringThe URL for the Lightning domain on your Salesforce instance. For example, https://myDomainName.lightning.force.com.
authTokenstringThe session ID or OAuth access token for a valid, active Salesforce session. You must obtain this token in your own code. Lightning Out doesn’t handle authentication for you. See Authentication from Lightning Out.

appName is required. The other three parameters are optional. Normally, you provide all four parameters.

You can’t use more than one standalone Aura dependency app on a page. You can call $Lightning.use() more than once, but you must reference the same dependency app in every call.

Add to and activate your components on the page with the $Lightning.createComponent() function.

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

NameTypeDescription
componentNamestringRequired. The name of the Lightning web component to add to the page, including the namespace. For example, "c:newExpenseForm".
attributesObjectRequired. 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, { }.
domLocatorElement or stringRequired. The DOM element or element ID that indicates where on the page to insert the created component.
callbackfunctionA function to call once 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. That is, you can call $Lightning.createComponent() multiple times, with multiple DOM locators, to add components to different parts of the page. Each component created this way must be specified in the page’s standalone Aura dependency app.

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

See Also