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.
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.
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(); });
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 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.
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.
.THIS.popoverclass { min-height: 100px; }
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; }
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.