Overlay Library

The lightning:overlayLib component provides access to methods you can use in your components to open and close modals and popovers.

Modals and popovers are overlays that display messages on the current app window. 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. Popovers can also be opened by other user interaction, such as clicking a button.

Include one <lightning:overlayLibrary aura:id="overlayLib"/> tag in the component that triggers the modal or popover, where aura:id is a unique local ID. Only one tag is needed in a component to open multiple messages.

Include the tag also in a component that closes a modal or popover, even if it doesn't open them.

A modal is triggered by user interaction, which can be a click of a button or link. The user must then interact with the modal before regaining control over the app. The modal blocks interaction with everything else on the page until it's dismissed. Press the Escape key or click the X close button to close the modal.

You can customize the modal header, body, and footer using parameters and components.

Modals inherit styling from modals in the Lightning Design System.

Here’s an example of a component c:modalOpener that uses a button to open a modal. When clicked, the button displays a modal with a custom body that's defined in another component.

modalOpener.cmp

The modalOpenerController.js client-side controller displays the modal. To create and display a modal, pass in the modal parameters using component.find('overlayLib').showCustomModal(), where overlayLib matches the aura:id specified in the <lightning:overlayLibrary> tag in the component markup. This example dynamically creates a custom body using $A.createComponent().

modalOpenerController.js

c:modalContent is a custom component that displays an icon and message as shown in this markup.

modalContent.cmp

The showCloseButton parameter when set to true causes the X close button to be displayed. The cssClass parameter specifies a class to apply to the modal.

Any custom CSS class you add with the cssClass parameter must be accompanied by the cMyCmp class, where c is your namespace and MyCmp is the name of the component that creates the modal. For this example, the class is cModalOpener. Adding this class ensures that the custom styling is properly scoped.

The closeCallback parameter causes a function to be called when the modal is closed. Firing an event is a typical use case.

_Create a Modal Footer _

Pass in a footer for the modal by using the footer parameter. You can pass a string or a component to include buttons, for example. Here's a client-side controller that creates a custom body and custom footer using $A.createComponents().

modalOpenerController.js

c:modalFooter is a custom component that displays Cancel and OK buttons as shown in this markup. The footer component includes the <lightning:overlayLibrary aura:id="overlayLib"/> tag so it can call the notifyClose() method in the client-side controller.

modalFooter.cmp

modalFooterController.js defines what happens when you click the footer buttons. The handleCancel function uses the notifyClose() method from the overlay library.

modalFooterController.js

showCustomModal() returns a promise, which is useful if you want to get a reference to the modal when it’s displayed. See Closing Modals and Popovers for more information.

Popovers display contextual information related to a particular element called the reference element. Popovers don’t interrupt like modals. A popover can be displayed when you hover over the reference element or click it. Popovers can also be opened by other user interaction, such as clicking a button, similar to modals.

Pressing the Escape key closes the popover. You can set a timeout to close it automatically. The popover is displayed after the reference element by default.

Popovers offer less customization than modals. The body and CSS can be customized but the popover doesn't provide a header or footer. You can pass in text or a custom component for the body.

Popovers inherit styling from popovers in the Lightning Design System.

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

popoverOpener.cmp

This popoverOpenerController.js client-side controller displays the popover. To create and display a popover, pass in the popover parameters using component.find('overlayLib').showCustomPopover(), where overlayLib matches the aura:id on the lightning:overlayLibrary instance.

Although this example passes in a string to the popover body parameter, you can also pass in a custom component like in the previous modal example.

popoverOpenerController.js

The referenceSelector specifies the class selector that's assigned to the div reference element. Note that the referenceSelector value must be unique for each popover in the DOM. If a page has multiple components that display popovers, you can generate a unique CSS selector based on something that's unique to the element.

Any custom CSS class you add with the cssClass parameter must be accompanied by the cMyCmp class, where c is your namespace and MyCmp is the name of the component that creates the popover. For this example, cPopoverOpener is the class name. Adding this class ensures that the custom styling is properly scoped.

showCustomPopover() returns a promise, which is useful if you want to get a reference to the popover when it’s displayed. See Closing Modals and Popovers for more information about using a promise to close overlays.

The CSS class sets the minimum height on the popover.

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.

Update the cssClass parameter. The cMyCmp class corresponds to your namespace and component name, and is case-sensitive.

There are two methods to close an overlay.

• close() method directly closes the modal or popover
• notifyClose() method fires an event that makes the modal or popover close itself

Using close()

The close() method relies on the overlay instance returned by showCustomModal() or showCustomPopover() in a promise. An overlay is separate from the component that opens it, so the overlay is not accessible to the component. The overlay instance must be added to the component before you can close it from the component.

This example shows how to use the close() method. The showCustomModal() method used in handleShowModal() returns a promise which provides the modal instance. Use the promise to obtain the instance and cache it in the component. This instance is used to close the modal directly from the component that opened the modal.

The handleCallback() method shows how a component such as c:openModal can use the close() method to close the modal that it opened, in response to an event or callback. The handleCallback() method sets a timeout to close the overlay.

Using notifyClose()

The notifyClose() method fires a close event, which bubbles up to the instance of the overlay. The modal or popover closes itself when it receives the close event. This method is useful for closing the overlay from a component other than the component that opened it.

For example, if you use a content component for the modal body, the content component can use notfiyClose() to close the modal without knowing the modal instance.

A modal can show an action in progress, confirm a user action, or communicate about an error. A user shouldn’t see multiple warning modals in one flow. Contrastingly, a popover calls attention to a problem or a potential problem with a field or record. For more information, see Messaging Design Guidelines.

Dynamically Creating Components

Component IDs