Alert

Use the lightning/alert module to create and open an alert modal from your component. Use LightningAlert on your components to communicate a state that affects the entire system, not just a feature or page.

Use LightningAlert.open() instead of the native window.alert() for a more consistent user experience. They have similar functions, but LightningAlert.open() works in cross-origin iframes, where the .alert() method is no longer supported in Chrome and Safari. Unlike window.alert(), LightningAlert.open() doesn’t halt execution on the page, it returns a Promise. Use async/await or .then() for any code you want to execute after the alert has closed.

Import LightningAlert from the lightning/alert module in the component that you use to open the alert modal, and call LightningAlert.open() with your attributes.

This example creates an alert modal with an error message and an OK button. The .open() function returns a promise that resolves when you click OK.

1<!-- c/myApp.html -->
2<template>
3    <lightning-button onclick={handleAlertClick} label="Open Alert Modal">
4    </lightning-button>
5</template>

1import { LightningElement } from "lwc";
2import LightningAlert from "lightning/alert";
3
4export default class MyApp extends LightningElement {
5  async handleAlertClick() {
6    await LightningAlert.open({
7      message: "this is the alert message",
8      theme: "error", // a red theme intended for error states
9      label: "Error!", // this is the header text
10    });
11    //Alert has been closed
12  }
13}

This module implements the prompt blueprint in the Salesforce Lightning Design System (SLDS). The prompt adapts to SLDS 1 or SLDS 2 styling based on the org’s theme or the container app that you use.

Use a combination of attributes to customize the alert modal style.

LightningAlert supports these attributes:

• message: Message text that displays in the alert.
• label: Header text, also used as the aria-label. Default string is Alert.
• variant: Two values, header and headerless. Default value is header.
• theme: Color theme for the header. The theme attribute supports these options from SLDS:
  • default: white
  • shade: gray
  • inverse: dark blue
  • alt-inverse: darker blue
  • success: green
  • info: gray-ish blue
  • warning: yellow
  • error: red
  • offline: ​black

If an invalid value is provided, LightningAlert uses the default theme. LightningAlert ignores the style attribute.

Test code that use LightningAlert by mocking the LightningAlert.open() method.

This example uses a button to open an alert dialog with text that changes when the alert opens.

1<button data-button onclick={handleClick}>Open Alert</button>
2<template if:true={alertViewed}>
3    <div data-text>Content Viewed</div>
4</template>
5<template if:false={alertViewed}>
6    <div data-text>Click to View Content</div>
7</template>

1import LightningAlert from 'lightning/alert';
2jest.mock('lightning/alert');
3​
4test(() => {
5    // Create and appendChild(element)
6​
7    const buttonEle = element.shadowRoot.querySelector('[data-button]');
8    const textEle = element.shadowRoot.querySelector('[data-text]');
9​
10    // Mock .open()
11    // No value passed since LightningAlert doesn't have a return value
12    LightningAlert.open = jest.fn().mockResolvedValue();
13    // Initial value
14    expect(textEle.textContent).toBe('Click to View Content');
15    // Click modal open button
16    buttonEle.click();
17​
18    // Click handler render cycle
19    await Promise.resolve();
20    // Render cycle triggered by tracked value {result}
21    await Promise.resolve();
22​
23    // Verify alertViewed has updated in template
24    expect(textEle.textContent).toBe('Content Viewed');
25    // Open triggered once
26    expect(LightningAlert.open.mock.calls).toHaveLength(1);
27})

The lightning/alert module implements the SLDS prompt blueprint, which follows the WAI-ARIA Authoring Practices for the alert and message dialogs pattern. Like modals, the alert dialog is a focus trap, but it specifies role="alertdialog" to indicate its severity.

Use the keyboard interaction guidelines on the SLDS site. When the dialog opens, focus moves to the header text on the dialog, which has tabindex="-1".

To close the dialog, you can press the Esc key. Alternatively, you can tab to the OK button and press Enter.

lightning/alert observes these roles, states, and properties.

• The section element has role="alertdialog" with an aria-description, which uses the value you provide for the message attribute.
• The aria-labelledby value on the section is set to the ID of the header text. Provide a header text by using the label attribute.