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 API module usage, see Base Components Categories: API Modules.

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.

The component renders using the <button> element.

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.

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, 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.

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

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.

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.

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.

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