Base Components Usage Patterns

Base components provide a consistent and reusable way to add functionality to your apps.

You can use a base component in one of several ways:

As markup in the component’s HTML template
As a module import in the component’s JavaScript
As a component class extension

This section covers common patterns for UI-based components only. For utility modules, see Base Components Categories: Utility Modules.

Use a Base Component in Markup

As base components are built on LWC using W3C web standards, you can use them in a template like regular HTML. Create an instance of a base component within the <template> HTML element.

Most of the base components that are UI-based follow this pattern. Let’s say you add a lightning-button base component to a template.

1<!-- c-custom-component -->
2<template>
3  <lightning-button
4    variant="brand"
5    label="Submit"
6    title="Submit this form"
7    onclick={handleClick}
8    class="slds-m-left_x-small"
9  ></lightning-button>
10</template>

The component renders using the <button> element.

1<!-- c-custom-component renders like this -->
2<lightning-button class="slds-m-left_x-small">
3  <button title="Submit this form" type="button" class="slds-button slds-button_brand">
4    Submit
5  </button>
6</lightning-button>

You can see how a base component renders in the DOM to understand its expected behavior. But don’t rely on any internal markup or CSS classes of a base component because they can change in future releases.

Note

Base components encapsulate many functionalities while making it easy for you to customize the look-and-feel of the component. For example, while variant and label attributes are part of the lightning-button base component’s [specification](https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button?type=Specifications, title, class, and onclick are HTML global attributes.

In this example, the variant and label attributes and the HTML global attributes are exposed as a public property so you can provide your own values in the custom component. The base component then passes your values down to the <button> element, implementing logic such as converting the variant value to a class on the <button> element.

Use a Base Component via a Module Import

Some UI-based components are available via a module import, including notification and toast components.

Import Notification Component Modules

These notification components require a module import.

For example, you use lightning/prompt by first importing the module, and then create an instance of the base component by calling a .open() method on the module.

1import { LightningElement } from "lwc";
2import LightningPrompt from "lightning/prompt";
3export default class MyComponent extends LightningElement {
4  async handlePrompt() {
5    // Returned value is input text if OK clicked
6    // or null if cancel is clicked
7    this.promptValue = await LightningPrompt.open({
8      message: "This is the prompt message",
9      label: "This is the header title",
10      defaultValue: "initial input value",
11      theme: "shade",
12    });
13  }
14}

The usage of these components resemble the window.*() APIs. As the HTML specification has deprecated support for the window.alert(), window.confirm(), and window.prompt() methods when used in a third-party context, we recommend that you use these notification components instead.

Unlike the window.*() APIs, these modules’ .open() method don’t halt execution on the page, and they each return a promise. Use async/await or .then() for any code that you want to execute after the modal closes.

Import Toast Component Modules

These toast components require a module import.

Although both toast components require a module import, 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.

Use a Base Component by Extension

Unless stated otherwise, extending any class besides LightningElement to create a Lightning web component isn’t supported. Only several base components allow for class extension.

lightning/modal
lightning/datatable

Using lightning/modal by extension:

Enables your custom modal component to appear as an overlay on the current app window.
Provides the open and close mechanisms for your custom modal component.

To create the modal’s UI, use the lightning-modal-header, lightning-modal-body, and lightning-modal-footer components.

Similarly, using lightning/datatable by extension enables you to create a custom data type for the datatable component.

See Also

Release Preview

This release is in preview. Features described here don't become generally available until the latest general availability date that Salesforce announces for this release. Before then, and where features are noted as beta, pilot, or developer preview, we can't guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.