Prompt

lightning-prompt

Create a prompt modal within your component that asks the user to provide information before they continue.

For Use In

Lightning Experience, Experience Builder Sites, Lightning Out (Beta), Standalone Lightning App

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

:::::tab

::component-playground{component="prompt" model="lwc" namespace="lightning"}

:::::

:::::tab

The lightning/prompt module provides the LightningPrompt component to create a prompt modal within your component. Use LightningPrompt on a component to ask the user to provide information before they continue.

note: Use LightningPrompt.open() instead of the native window.prompt() for a more consistent user experience. They have similar functions, but LightningPrompt.open() works in cross-origin iframes, where the .prompt() method is no longer supported in Chrome and Safari. Unlike window.prompt(), LightningPrompt.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 prompt has closed.

Design

lightning/prompt 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.

Usage

Import LightningPrompt from the lightning/prompt module in the component that opens the prompt modal, and call LightningPrompt.open() with your desired attributes.

This example creates a prompt modal with a header, message, and two buttons. If you enter text and click OK in the prompt, the .open() function returns a promise that resolves to the input value. If you click Cancel, the function returns a promise that resolves to null.

<!-- c/myApp.html -->
<template>
    <lightning-button onclick={handlePromptClick} label="Open Prompt Modal">
    </lightning-button>
</template>

import { LightningElement } from "lwc";
import LightningPrompt from "lightning/prompt";

export default class MyApp extends LightningElement {
  handlePromptClick() {
    LightningPrompt.open({
      message: "this is the prompt message",
      //theme defaults to "default"
      label: "Please Respond", // this is the header text
      defaultValue: "initial input value", //this is optional
    }).then((result) => {
      //Prompt has been closed
      //result is input text if OK clicked
      //and null if cancel was clicked
    });
  }
}

LightningPrompt supports these attributes:

• message: Message text that displays in the prompt.
• defaultValue: Optional. Initial leading text for the input text box.
• label: Header text, also used as the aria-label. Default string is Prompt.
• variant: See the Variants section.
• theme: See the Themes section.

Component Styling

Use a combination of variants, themes, and utility classes to customize your prompts.

Variants

Specify the variant attribute with one of these values.

• header is the default variant, which displays the prompt with header text
• headerless displays the prompt without header text

Themes

Specify the theme attribute for the prompt header with one of these color 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, LightningPrompt uses the default theme. LightningPrompt ignores the style attribute.

Utility Classes

To apply additional styling, use the SLDS utility classes with the class attribute.

Test Your Prompt

Code using LightningPrompt can be tested by mocking the LightningPrompt.open() method.

This example uses a button to open a prompt dialog and sets the result in a template.

<button data-button onclick={handleClick}>Open Prompt</button>
<div data-result>{result}</div>

import LightningPrompt from 'lightning/prompt';
jest.mock('lightning/prompt');
​
test(() => {
    // Create and appendChild(element)
​
    const buttonEle = element.shadowRoot.querySelector('[data-button]');
    const resultEle = element.shadowRoot.querySelector('[data-result]');
​
    // Mock .open()
    // Pass string representing input text if testing when user clicks "OK"
    // Pass null if testing when user clicks "Cancel"
    LightningPrompt.open = jest.fn().mockResolvedValue('test value');
    // Initial value
    expect(resultEle.textContent).toBe('unknown');
    // Click modal open button
    buttonEle.click();
​
    // Click handler render cycle
    await Promise.resolve();
    // Render cycle triggered by tracked value {result}
    await Promise.resolve();
​
    // Verify result is set in the template
    expect(resultEle.textContent).toBe('test value');
    // Open triggered once
    expect(LightningPrompt.open.mock.calls).toHaveLength(1);
})

:::::

:::::tab ::component-specification{component="prompt" model="lwc" namespace="lightning"}

:::::

::::::