Notifications Library
Displays messages via notices and toasts. This component requires API version 41.0 and later.
Descriptor
lightning:notificationsLibraryTargets
Lightning Experience, Experience Builder Sites, Salesforce Mobile App
Messages can be displayed in notices and toasts. Notices alert users to system-related issues and updates. Toasts enable you to provide feedback and serve as a confirmation mechanism after the user takes an action.
Include one <lightning:notificationsLibrary aura:id="notifLib"/> tag in the component that triggers the notifications, where aura:id is a unique local ID. Only one tag is needed for multiple notifications.
Notices
Notices interrupt the user's workflow and block everything else on the page. Notices must be acknowledged before a user regains control over the app again. As such, use notices sparingly. They are not suitable for confirming a user’s action, such as before deleting a record. To dismiss the notice, only the OK button is currently supported.
Notices inherit styling from prompts in the Lightning Design System.
To create and display a notice, pass in the notice attributes using component.find('notifLib').showNotice(), where notifLib matches the aura:id on the lightning:notificationsLibrary instance.
Here’s an example that contains a button. When clicked, the button displays a notice with the error variant.
<aura:component> <lightning:notificationsLibrary aura:id="notifLib"/> <lightning:button name="notice" label="Show Notice" onclick="{!c.handleShowNotice}"/> </aura:component> This client-side controller displays the notice.
({ handleShowNotice : function(component, event, helper) { component.find('notifLib').showNotice({ "variant": "error", "header": "Something has gone wrong!", "message": "Unfortunately, there was a problem updating the record.", closeCallback: function() { alert('You closed the alert!'); } }); } }) To create and display a notice, pass in the notice attributes using component.find('notifLib').showNotice(), where notifLib matches the aura:id on the lightning:notificationsLibrary instance.
Parameters
| Parameter | Type | Description |
|---|---|---|
| header | String | The heading that’s displayed at the top of the notice. |
| title | String | The title of the notice, displayed in bold. |
| message | String | The message within the notice body. New lines are replaced by <br/> and text links by anchors. |
| variant | String | Changes the appearance of the notice. Accepted variants are info, warning, and error. This value defaults to info. |
| closeCallback | Function | A callback that’s called when the notice is closed. |
Toasts
Toasts are less intrusive than notices and are suitable for providing feedback to a user following an action, such as after a record is created. A toast can be dismissed or can remain visible until a predefined duration has elapsed.
Toasts inherit styling from toasts in the Lightning Design System.
To create and display a toast, pass in the toast attributes using component.find('notifLib').showToast(), where notifLib matches the aura:id on the lightning:notificationsLibrary instance.
Here’s an example that contains a button. When clicked, the button displays a toast with the info variant and remains visible until you click the close button, denoted by the X in the top right corner.
<aura:component> <lightning:notificationsLibrary aura:id="notifLib"/> <lightning:button name="toast" label="Show Toast" onclick="{!c.handleShowToast}"/> </aura:component> This client-side controller displays the toast.
({ handleShowToast : function(component, event, helper) { component.find('notifLib').showToast({ "title": "Success!", "message": "The record has been updated successfully." }); } }) Displaying Links in Toasts and Notices
To display a link in the message, use the messageData attribute to pass in url and label values for the message string.
({ handleShowToast : function(component, event, helper) { component.find('notifLib').showToast({ "title": "Success!", "message": "Record {0} created! See it {1}!", "messageData": [ 'Salesforce', { url: 'http://www.salesforce.com/', label: 'here', } ] }); }) Using messageData is not supported for the Salesforce mobile app.
Parameters
| Parameter | Type | Description |
|---|---|---|
| title | String | The title of the toast, displayed as a heading. |
| message | String | A string representing the message. It can contain placeholders in the form of {0} ... {N}. The placeholders are replaced with the links on messageData. |
| messageData | String[] | Object | url and label values that replace the {index} placeholders in the message string. |
| variant | String | Changes the appearance of the notice. Accepted variants are info, success, warning, and error. This value defaults to info. |
| mode | String | Determines how persistent the toast is. The default is dismissable. Valid modes are:
|
Design Guidelines
A notice appears when the system needs to communicate a message to the user; it doesn’t show up as a result of user action. A notice should rarely appear and generally should not be a part of a typical user flow. Contrastingly, a toast appears in reaction to a user action: creating, editing, deleting. For example, a user edits a record and saves it. For more information, see Messaging Design Guidelines.
