lightning:overlayLibrary

lightning:overlayLibrary provides an easy way to display relevant information and feedback. This component requires API version 41.0 and later. This component is supported in Lightning Experience, Salesforce app, and Lightning communities only.

Messages can be displayed in modals and popovers. Modals display a dialog in the foreground of the app, interrupting a user’s workflow and drawing attention to the message. Popovers display relevant information when you hover over a reference element. Include one <lightning:overlayLibrary aura:id="overlayLib"/> tag in the component that triggers the messages, where aura:id is a unique local ID. Only one tag is needed for multiple messages.

Modals

A modal blocks everything else on the page until it’s dismissed. A modal must be acknowledged before a user regains control over the app again. A modal is triggered by user interaction, which can be a click of a button or link. The modal header, body, and footer are customizable. Pressing the Escape key or clicking the close button closes the modal.

Modals block everything else in the app until they are dismissed.

Here’s an example that contains a button. When clicked, the button displays a modal with a custom body.

<aura:component>    
    <lightning:overlayLibrary aura:id="overlayLib"/>
    <lightning:button name="modal" label="Show Modal" onclick="{!c.handleShowModal}"/>
</aura:component>

Your client-side controller displays the modal. To create and display a modal, pass in the modal attributes using component.find('overlayLib').showCustomModal(), where overlayLib matches the aura:id on the lightning:overlayLibrary instance.

({    
    handleShowModal: function(component, evt, helper) {
        var modalBody;
        $A.createComponent("c:modalContent", {},
                           function(content, status) {
                               if (status === "SUCCESS") {
                                   modalBody = content;
                                   component.find('overlayLib').showCustomModal({
                                       header: "Application Confirmation",
                                       body: modalBody, 
                                       showCloseButton: true,
                                       cssClass: "mymodal",
                                       closeCallback: function() {
                                           alert('You closed the alert!');
                                       }
                                   })
                                   
                               }
                               
                           });
    }
})

c:modalContent is a custom component that displays an icon and message.

<aura:component>
    <lightning:icon size="medium" iconName="action:approval" alternativeText="Approved" />
    Your application has been approved.
</aura:component>

You can pass in your own footer via the footer attribute. This example creates a custom body and footer using $A.createComponents().

handleShowModalFooter : function (component, event, helper) {
    var modalBody;
    var modalFooter;
    $A.createComponents([
        ["c:modalContent",{}],
        ["c:modalFooter",{}]
    ],
    function(components, status){
        if (status === "SUCCESS") {
            modalBody = components[0];
            modalFooter = components[1];
            component.find('overlayLib').showCustomModal({
               header: "Application Confirmation",
               body: modalBody, 
               footer: modalFooter,
               showCloseButton: true,
               cssClass: "my-modal,my-custom-class,my-other-class",
               closeCallback: function() {
                   alert('You closed the alert!');
               }
           })
        }
    }
   );
}

c:modalFooter is a custom component that displays two buttons.

<aura:component>
    <lightning:overlayLibrary aura:id="overlayLib"/>
    <lightning:button name="cancel" label="Cancel" onclick="{!c.handleCancel}"/>
    <lightning:button name="ok" label="OK" variant="brand" onclick="{!c.handleOK}"/>
</aura:component>

Define what happens when you click the buttons in your client-side controller.

({
    handleCancel : function(component, event, helper) {
        //closes the modal or popover from the component
        component.find("overlayLib").notifyClose();
    },
    handleOK : function(component, event, helper) {
        //do something
    }
})

showCustomModal() and showCustomPopover() return a promise, which is useful if you want to get a reference to the modal when it’s displayed.

component.find('overlayLib').showCustomModal({
   //modal attributes
}).then(function (overlay) {
    //closes the modal immediately
    overlay.close();
});
Modals inherit styling from modals in the Lightning Design System.

Attributes

Attribute Name Attribute Type Description Required?
header Object The heading that’s displayed at the top of the modal.
body Object The body of the modal.
footer Object The modal footer.
showCloseButton Boolean Specifies whether to display the close button on the modal. The default is true.
cssClass String A comma-separated list of CSS classes for the modal. Applies to visible markup only.
closeCallback Function A callback that’s called when the modal is closed.

Methods

You can use the following methods on the modal instance returned by the promise.

close(): Dismisses and destroys the modal.

hide(): Hides the modal from view.

show(): Displays the modal.

Popovers

Popovers display contextual information on a reference element and don’t interrupt like modals. A popover can be displayed when you hover over or click the reference element. Pressing the Escape key closes the popover. The default positioning of the popover is on the right of the reference element.

Popovers display contextual information.

Here’s an example that contains a button and a reference div element. When clicked, the button displays a popover. The popover also displays when you hover over the div element.

<aura:component>    
    <lightning:overlayLibrary aura:id="overlayLib"/>
    <lightning:button name="popover" label="Show Popover" onclick="{!c.handleShowPopover}"/>    
    <div onmouseover="{!c.handleShowPopover}">Popover should display if you hover over here.</div>
</aura:component>

Your client-side controller displays the popover. Although this example passes in a string to the popover body, you can also pass in a custom component like in the previous modal example. Any custom CSS class you add must be accompanied by the cMyCmp class, where c is your namespace and MyCmp is the name of the component that creates the popover. Adding this class ensures that the custom styling is properly scoped.

({
    handleShowPopover : function(component, event, helper) {
        component.find('overlayLib').showCustomPopover({
            body: "Popovers are positioned relative to a reference element",
            referenceSelector: ".mypopover",
            cssClass: "popoverclass, cMyCmp"
        }).then(function (overlay) {
            setTimeout(function(){ 
                //close the popover after 3 seconds
                overlay.close(); 
            }, 3000);
        });
    }
})

To create and display a popover, pass in the popover attributes using component.find('overlayLib').showCustomPopover(), where overlayLib matches the aura:id on the lightning:overlayLibrary instance.

The CSS class sets the minimum height on the popover.
.THIS.popoverclass {
    min-height: 100px;
}
Popovers inherit styling from popovers in the Lightning Design System.

To append popover modifier classes, include them in cssClass. The following example adds the slds-popover_walkthrough class for a dark theme. The pointer is hidden and replaced by the slds-nubbin_left class. To hide the pointer, add the following CSS rule.

.THIS.no-pointer .pointer{
    visibility: hidden;
}
Update the cssClass attribute. The cMyCmp class corresponds to your namespace and component name, and is case-sensitive.
cssClass: "slds-nubbin_left,slds-popover_walkthrough,no-pointer,cMyCmp"

Attributes

Attribute Name Attribute Type Description Required?
body Object The body of the popover.
referenceSelector Object The reference element to which the popover is appended. The popover is appended to the right of the reference element.
cssClass String A comma-separated list of CSS classes for the popover. Applies to visible markup only.

Methods

You can use the following methods on the modal instance returned by the promise.

close(): Dismisses and destroys the modal.

hide(): Hides the modal from view.

show(): Displays the modal.