Platform Show Toast Event (Beta)

lightning/platformShowToastEvent

Provides feedback and confirmation after a user action.

For Use In

Lightning Experience, Experience Builder Sites, Salesforce Mobile App

::::::tabset{tabs='[ "Develop", "Specifications"]'}

:::::tab

Display toasts to provide feedback to a user following an action, such as after a record is created.

lightning/platformShowToastEvent isn't supported in LWR sites for Experience Cloud. Use lightning/toast in LWR sites instead. To specify your toast position and the maximum number of toasts to display, use lightning/platformShowToastEvent or lightning/toast with lightning/toastContainer.

You can style a toast to provide information, an error, a success, or a warning. You can also configure the visibility of the toast. It remains visible for 20 seconds, until the user clicks to dismiss it, or a combination of both.

To trigger a toast from a Lightning web component, in the component's JavaScript class, import ShowToastEvent from lightning/platformShowToastEvent. Create a ShowToastEvent with a few parameters, and dispatch it. The app handles the rest.

In this example, when a user clicks the button, the app displays a toast with the info variant, which is the default. The toast remains visible for 20 seconds or until the user clicks the close button, denoted by the X in the top right corner, which is also the default.

<template>
    <lightning-button label="Show Toast" onclick={showToast}>
    </lightning-button>
</template>

The showToast function creates and dispatches the event. An info toast displays in Lightning Experience for 5 seconds or until the user clicks to close it.

import { LightningElement } from "lwc";
import { ShowToastEvent } from "lightning/platformShowToastEvent";
export default class MyComponent extends LightningElement {
  showToast() {
    const event = new ShowToastEvent({
      title: "Get Help",
      message:
        "Salesforce documentation is available in the app. Click ? in the upper-right corner.",
    });
    this.dispatchEvent(event);
  }
}

Displaying Links in Toasts

To display a link in the message, use the messageData attribute to pass in url and label values for the message string. In the following example, handleButtonClick() displays a toast with a link in the message. handleRecordClick() displays a toast with a link to a record, which uses the lightning/navigation module to generate the URL.

import { LightningElement } from "lwc";
import { ShowToastEvent } from "lightning/platformShowToastEvent";
import { NavigationMixin } from "lightning/navigation";

export default class LightningToastExample extends NavigationMixin(LightningElement) {
  handleButtonClick() {
    const event = new ShowToastEvent({
      title: "Success!",
      message: "Record {0} created! See it {1}!",
      messageData: [
        "Salesforce",
        {
          url: "http://www.salesforce.com/",
          label: "here",
        },
      ],
    });
    this.dispatchEvent(event);
  }

  handleRecordClick() {
    this[NavigationMixin.GenerateUrl]({
      type: "standard__recordPage",
      attributes: {
        recordId: "003xx000000001eAAA",
        actionName: "view",
      },
    }).then((url) => {
      const event = new ShowToastEvent({
        title: "Success!",
        message: "Record {0} created! See it {1}!",
        messageData: [
          "Salesforce",
          {
            url,
            label: "here",
          },
        ],
      });
      this.dispatchEvent(event);
    });
  }
}

Parameters

Parameter	Type	Description
`title`	String	(Required) The title of the toast, displayed as a heading.
`message`	String	(Required) A string representing the body of the message. It can contain placeholders in the form of `{0} ... {N}`. The placeholders are replaced with the links on `messageData`.
`messageData`	String[] or Object	`url` and `label` values that replace the `{index}` placeholders in the `message` string.
`variant`	String	Changes the appearance of the notice. Toasts inherit styling from toasts in the Lightning Design System. Valid values are: `info` (default), `success`, `warning`, and `error`.
`mode`	String	Determines how persistent the toast is. Valid values are: `dismissible` (default), remains visible until you click the close button or 20 seconds has elapsed, whichever comes first; `pester`, remains visible for 20 seconds and disappears automatically. No close button is provided; `sticky`, remains visible until you click the close button.

Design Guidelines

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.

Usage Considerations

lightning/platformShowToastEvent uses an event-based mechanism to display a toast, and it's not supported in environments like LWR sites for Experience Cloud or standalone apps. We recommend that you use lightning/toast instead.

This component has usage differences from its Aura counterpart. See Base Components: Aura Vs Lightning Web Components in the Lightning Web Components Developer Guide.

LWC Recipes

The LWC Recipes GitHub repository contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses lightning/platformShowToastEvent, see the following components in the LWC Recipes repo.

c-lds-create-record
c-misc-toast-notification