lightning:container

Used to contain content that uses a third-party javascript framework such as Angular or React.

The lightning:container component allows you to host content developed with a third-party framework within a Lightning component. The content is uploaded as a static resource, and hosted in an iFrame. The lightning:container component can be used for single-page applications only.

This is a simple example of lightning:container, which loads an app that's uploaded as a static resource named myReactApp.

<aura:component access="global" implements="flexipage:availableForAllPageTypes">
    <lightning:container src="{!$Resource.myReactApp + '/index.html'}"/>
</aura:component>

To pass a value of an attribute to the container via its URL, define the attribute in your component and pass it in using the src attribute.

<aura:component>
    <aura:attribute access="global" name="greeting" type="String" required="true" default="Hello"/>
    <div>
        <lightning:container src="{!$Resource.myReactApp + '/index.html?greeting=' + v.greeting}"/>
    </div>
</aura:component>

You can also implement communication to and from the framed application, allowing it to interact with Salesforce. Use the message() function in the Javascript controller to send messages to the application, and specify a method for handling messages with the component’s onmessage attribute.

This example defines attributes for a message to send from the container to the Lightning component and for a message received.

<aura:component access="global" implements="flexipage:availableForAllPageTypes" >
    <aura:attribute name="messageToSend" type="String" default=""/>
    <aura:attribute name="messageReceived" type="String" default=""/>
    <div>
        <lightning:input name="messageToSend" value="{!v.messageToSend}" label="Message to send to Angular app: "/>
        <lightning:button label="Send" onclick="{!c.sendMessage}"/>       
        <lightning:textarea name="messageReceived" value="{!v.messageReceived}" label="Message received from Angular app: "/>        
        <lightning:container aura:id="AngularApp"
                             src="{!$Resource.SendReceiveMessages + '/index.html'}"
                             onmessage="{!c.handleMessage}"/>
    </div>
</aura:component>   

The client-side controller uses the message() function to send a simple JSON payload to an AngularJS app.

({
    sendMessage : function(component, event, helper) {
        var msg = {
            name: "General",
            value: component.get("v.messageToSend")
        };
        component.find("AngularApp").message(msg);
    },
    handleMessage: function(component, message, helper) {
        var payload = message.payload;
        var name = payload.name;
        if (name === "General") {
            var value = payload.value;
            component.set("v.messageReceived", value);
        }
        else if (name === "Foo") {
            // A different response
        }
    },
})

Because you define the controller-side message handling yourself, you can use it to handle any kind of message payload. You can, for example, send just a text string or return a structured JSON response.

Usage Considerations

When specifying the src of the container, don’t specify a hostname. Instead, use $Resource with dot notation to reference your application, uploaded as a static resource.

For more information, see the Lightning Components Developer Guide.

Accessibility

Use the alternativeText attribute to provide assistive text for the lightning:container.

Methods

The component supports the following method.

message(): Sends a user-defined message from the component to the iFrame content.

Attributes

Attribute Name Attribute Type Description Required?
alternativeText String Used for alternative text in accessibility scenarios.
body Component[] The body of the component. In markup, this is everything in the body of the tag.
class String The CSS class for the iframe element.
onerror Action The client-side controller action to run when an error occurs when sending a message to the contained app.
onmessage Action The client-side controller action to run when a message is received from the contained content.
src String The resource name, landing page and query params in url format. Navigation is supported only for the single page identified. Yes