Displaying User Notifications with the Lightning Component Framework

In this blog post, we explore a Lightning event and a component that displays user notifications: toasts and modals. We’ll share best practices and sample code for each of these components.

Toasts

Toasts are the simplest form of notification a developer can use to display a notification dynamically.

They are used to provide basic user feedback with a limited amount of text (if the text is too long, consider using a modal). Unless set to “sticky” mode, they’re displayed for a limited duration and don’t block user interactions.

In Lightning Experience, Salesforce1, and Lightning communities, you aren’t required to directly inject the toast component markup in your code. Instead, you can fire a force:showToast (documentation) application event. The one.app container handles this event and takes care of the markup, placement, and animation of the toast so that you can focus on the content itself.

You simply fire the event from your component’s controller or helper:

var toastEvent = $A.get("e.force:showToast");
toastEvent.setParams({
    title: "Success!",
    message: "Congrats, it works!",
    type: "success"
});
toastEvent.fire();

Toasts displayed by firing the force:showToast event:

• Are displayed above all content at the top center of the screen
• Stack up to display up to three toasts
• Don’t support HTML at all (characters are escaped)
• Only support links when a message template is specified (check the documentation for more details)

Feel free to try it out with this sample gist.

Modals

Modals are a more advanced way of interacting with users. Unlike toasts, modals focus user interactions by applying an overlay over the screen. Modals are more versatile as they can display a long message, act as a confirmation dialog, capture data with a form, or display a loading message such as file upload progress.

When using modals, consider these UX best practices:

• Avoid displaying a series of modals.
• Don’t use a modal to display a success message, use a toast instead.
• When displaying long content in a modal, add a vertical scroll bar to the modal’s body (the modal footer and its buttons must be kept visible).

Modals come up with several configuration options (optional header and footer, optional close icon, extra wide body, and so on). But these require more code as there’s no Base Lightning component available out of the box for now. That’s subject to change (forward-looking statement) in Winter ’18 according to our Lightning component roadmap.

As a convenience, I’ve built and open sourced such a Lightning modal component (AppExchange listing, GitHub repository) that you can freely reuse in your projects. This means that you’re no longer required to rebuild the modal markup and logic each time you need one.

This component can be declared via the following markup:

<ui_modal:modal aura:id="theStaticModal" title="Modal title" isDirectional="true" isLarge="false" hasCloseIcon="true">
    <!-- Modal tagline -->
    <aura:set attribute="tagline">
        Here’s a tagline if you need it.
    </aura:set>

    <!-- Modal body -->
    <div>Hello, this is the <b>modal</b>'s message.<br/>
    It supports <u>any</u> type of markup including Lightning components</div>

    <!-- Modal footer -->
    <aura:set attribute="footer">
        <lightning:button label="Cancel" onclick="{!c.onCancel}" />
        <lightning:button variant="brand" label="Confirm" onclick="{!c.onConfirm}" />
    </aura:set>
</ui_modal:modal>

Then, it’s displayed with this line of code in your component’s controller or helper:

component.find("theStaticModal").openModal();

As an alternative to declaring the modal with markup, you can create the modal dynamically with this JavaScript code:

$A.createComponent(
    "ui_modal:modal", {'aura:id': 'theDynamicModal'},
    function(newModal, status, errorMessage){
        if (status === "SUCCESS") {
            //Add the new modal to the app body
            var body = component.get("v.body");
            body.push(newModal);
            component.set("v.body", body);
            // Display an alert modal with a title, a message and an OK button
            // This method is a shorthand that:
            // - pre-populates the modal attributes
            // - displays the modal
            newModal.openModalAlert("Alert", "Hello world!");
        } else {
            console.log("Failed to create modal");
            console.log("Error status: " + status);
            console.log("Error message: " + errorMessage);
        }
    }
);

Conclusion

You now have a better understanding of displaying user notifications using a Lightning Component Framework. Toasts are the simplest form of notification for a limited amount of text. Modals can display a long message, act as a confirmation dialog, capture data with a form, or display a loading message. I provided sample code for each of these components for you to explore.

You now have the tools and knowledge that enable you to display the right type of user notifications from your custom Lightning components.

Remember to keep an eye out for the Lightning component roadmap as two user feedback components are coming up in Winter ’18 (forward-looking statement): lightning:modal and lightning:notifications.

Resources

• Lightning force:showToast event
  • Documentation
  • Sample code
• Lightning modal component
  • AppExchange listing
  • Source and sample code