Using New LightningModal Component in LWC

A Modal popup is one of the most used features in any UI Framework and LWC is no different. There was no standard Modal component provided by the LWC framework, until today. In this article, we will check the steps for using new lightningmodal component in LWC.

Before LightningModal was introduced in the Winter23 release, developers used to resort to using <template></template> tag, custom CSS, and JS handlers to mimic creating a modal popup in LWC.

This article is designed with beginners in mind, ensuring that you can follow along easily and implement the concepts in your Salesforce instance.

What is the new LightningModal Component?

The new LightningModal Component helps developers create an overlay on top of the UI without the overhead of creating the feature from the ground up.

But, even after being a native component of LWC Framework, there is no <lightning-modal> <lightning-modal> tag that you can start using straightaway to implement a modal. Something that other UI frameworks have.

Two steps to start using new LightningModal Component in LWC

Step 1:

Create your own custom modal component by extending LightningModal

Step 2:

Calling your custom modal component from other components.

Step 1: Create a Custom Modal Component extending LightningModal

The first step in the process of using LightningModal is the create your own custom Modal LWC component by extending the LightningModal component provided by the LWC framework.

They use the helper lightning-modal-* components to provide a header, footer, and the body of the modal.

• lightning-modal-body
• lightning-modal-header
• lightning-modal-footer

Let’s start by creating a custom modal component called MyModal from the vscode.

HTML Code

<template>
    <lightning-modal-header label={modalHeader}></lightning-modal-header>
    
    <lightning-modal-body>
        {content}
    </lightning-modal-body>
    
    <lightning-modal-footer>
        <lightning-button label="Close" onclick={handleClose}></lightning-button>
    </lightning-modal-footer>
</template>

Explanation

We will first import the LightningModal component from the lightning/modal module in our JS Code (explained below).

In our HTML Code, we use the helper lightning-modal-* components to construct the UI of our custom modal. The lightning-modal-header and lightning-modal-footer components are optional but recommended.

The helper components render in the order they appear in the HTML Code.

As you can see in the example above we are using a modalHeader property to dynamically show the header name and content to show the modal body.

The lightning-button in the footer calls handleClose hander to close the modal window.

JS Code

import { api } from 'lwc';
import LightningModal from 'lightning/modal';

export default class MyModalDemo extends LightningModal  {
    @api content;
    @api modalHeader;
    handleClose() {
        this.close('okay');
    }
}

Explanation

In our JS Code, we extend the LightningModal component from the lightning/modal module. This gives us access to helper components, methods, and events to customize the behavior of our custom modal component further.

We have declared two properties with the @api decorator, as the values for these will be passed from the component which will invoke our modal component.

The handleClose handler is used to close the modal overlay/popup, using this.close helper method provided by the LightningModal component.

Step 2: Calling your custom modal component from other components.

Now that you have created your custom modal component using LightningModal in Step1, its time to invoke and show the Modal in the UI.

We will now create a second LWC Component called DemoLightningModal in the vscode.

HTML Code

<template>
    <div style="background:white;padding:10px;margin-bottom:10px">LightningModal Component Demo</div>

    <lightning-button label="Show Modal" onclick={showModal}></lightning-button>

</template>

Explanation

Keeping the code simple, we create a div with a text, this is specifically for the demo so you can ignore that.

We create a lightning-button that call a showModal handler in the JS Code.

JS Code

import { LightningElement } from 'lwc';
import MyModalDemo from 'c/myModalDemo';
export default class ModalComponentDemo extends LightningElement {
    async showModal(){
        const result = await MyModalDemo.open({
            // `label` is not included here in this example.
            // it is set on lightning-modal-header instead
            size: 'large',
            description: 'Accessible description of modal\'s purpose',
            content: 'This is LightningModal Example',
            modalHeader : 'My Modal Heading'
        });
        // if modal closed with X button, promise returns result = 'undefined'
        // if modal closed with OK button, promise returns result = 'okay'
        console.log(result);
    }
}

Explanation

This is where all the magic happens. At the top of the code, you can see we are importing our custom modal component.

Then, from the showModal handler, we are calling the open handler method of our modal component. Now you might be wondering where did the open handler came from, we didn’t define it.

The open handler is another helper method that is imported from the LightningModal component, in our custom modal component. This is another helper method, apart from close, provided by the LightningModal component.

When we call the open helper method of the modal, we can pass certain attributes that control the behavior and UI of the modal popup.

Attributes

NAME	TYPE	ACCESS	REQUIRED	DEFAULT	DESCRIPTION
description		global			Sets the modal’s accessible description.
disable-close		global			Prevents closing the modal by normal means like the ESC key, the close button, or `.close()`.
label		global	Yes		Sets the modal’s title and assistive device label.
size		global		medium	How much of the viewport width does the modal uses. Supported values are small, medium, large, or full.

Demo

Conclusion

LightningModal component is introduced as part of the Winter23 release and handles the basic modal requirements well, but there might be some complex requirements that the LightningModal component might not address.

The ability to pass dynamic HTML tags as a child in lightning-modal-body is one of the important features that need more exploration when using the LightningModal component. For such complex requirements, you might still want to follow the route to create a modal popup in lwc component.

Feel free to try copy and paste the code in your vscode and try out this new component provided by Salesforce.

If you have any questions, feedback, or suggestions, please share them in the comment section below. Share this article with your developer friends who might find it useful.

---