The Salesforce Developers website will undergo maintenance on May 29, 2024 from 3:00 a.m. UTC to 10:00 a.m. UTC. The maintenance process may affect the availability of our documentation. Please plan accordingly.

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 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 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:

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 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:

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

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


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.


Get the latest Salesforce Developer blog posts and podcast episodes via Slack or RSS.

Add to Slack Subscribe to RSS