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 Lightning Out 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 Lightning Out app with the $Lightning.use() function.
The $Lightning.use() function takes four arguments.
| Name | Type | Description |
|---|---|---|
appName | string | Required. The name of your Lightning Out app, including the namespace. For example, "c:expenseAppDependencies". |
callback | function | A function to call after 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 app being ready. |
lightningEndPointURI | string | The URL for the Lightning domain on your Salesforce instance. For example, https://myDomainName.lightning.force.com. |
authToken | string | The 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.
If a user is authenticated with the Lightning Out endpoint, you must set the session in $Lightning.use() with the authToken parameter.
You can’t use more than one Lightning Out app on a page. You can call $Lightning.use() more than once, but you must reference the same Lightning Out 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.
| 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 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 Lightning Out 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