As modular building blocks, base components follow several structures: composition or flat structure. Understanding the differences can be helpful as you work with base components or build your own custom components.
Many base components can compose other base components. We sometimes refer to this relationship as parent and child components. A common pattern for working with base components is to compose them declaratively like this.
1<lightning-breadcrumbs>
2 <lightning-breadcrumb label="Parent Account" href="path/to/place/1">
3 </lightning-breadcrumb>
4 <lightning-breadcrumb label="Case" href="path/to/place/2">
5 </lightning-breadcrumb>
6</lightning-breadcrumbs>You can create multiple instances of a nested base component via data from a JavaScript object. For example, if you have a large list to iterate through, you can use the for:each directive to display a list of menu items on the lightning-button-menu component.
1<lightning-button-menu alternative-text="Show menu">
2<template for:each={menuItems} for:item="item" >
3 <lightning-menu-item
4 label={item.label}
5 value={item.value}
6 key={item.value}>
7 </lightning-menu-item>
8</template>
9</lightning-button-menu>In the component’s JavaScript file, pass in the label and value pairs to lightning-menu-item.
1menuItems = [
2 { label: "Not Started", value: "red" },
3 { label: "In Progress", value: "yellow" },
4 { label: "Done", value: "green" },
5];Here are some examples of base components that compose other base components.
| Parent | Child | Description |
|---|---|---|
lightning-accordion | lightning-accordion-section | Displays content in sections that can be expanded and collapsed |
lightning-breadcrumbs | lightning-breadcrumb | Displays a hierarchy path of the page you’re visiting |
lightning-button-group | lightning-button | Displays a group of buttons |
lightning-button-menu | lightning-menu-item | Displays a dropdown menu with a list of action items |
lightning-layout | lightning-layout-item | Displays content in a responsive grid system |
lightning-progress-indicator | lightning-progress-step | Displays an indication on the progress of a process |
lightning-record-edit-form | lightning-input-field | Displays a form for record editing |
lightning-record-view-form | lightning-output-field | Displays record data |
lightning-tabset | lightning-tab | Displays content in sections that can be shown one at a time |
lightning-vertical-navigation | lightning-vertical-navigation-section | Displays a list of links for navigation |
Base component composition is made possible by using slots in the parent components. For more information, see Pass Markup to a Base Component Slot.
Some base components, such as lightning-combobox and lightning-select, render child components internally. This presents a flatter component surface for you to work with.
1<lightning-select
2 label="Quantity"
3 value={value}
4 options={options}
5 onchange={handleChange}></lightning-select>In this lightning-select example, you can use a getter to pass in the options. The component takes care of rendering the <select> and <option> tags.
1import { LightningElement } from "lwc";
2export default class SelectExample extends LightningElement {
3 value = "";
4 get options() {
5 return [
6 { label: "choose one...", value: "" },
7 { label: "one", value: "1" },
8 { label: "two", value: "2" },
9 { label: "three", value: "3" },
10 ];
11 }
12 handleChange(event) {
13 this.value = event.detail.value;
14 }
15}When you compare composition and flat structures, the latter uses an attribute like options for you to pass in your configuration information.
Here are some examples of base components that use a flat structure.
| Base Component | Usage |
|---|---|
lightning-checkbox-group | Pass in the label and value that describe checkbox options to the options attribute. |
lightning-combobox | Pass in the label and value that describe a menu item to the options attribute. |
lightning-dual-listbox | Pass in the label and value that describe a menu item to the options attribute. |
lightning-datatable | Pass in the label, fieldName, and type to the columns attribute. Pass in column data to the data attribute. |
lightning-map | Pass in the map markers to the map-markers attribute. |
lightning-pill-container | Pass in the pill items to the items attribute. |
lightning-radio-group | Pass in the label and value that describe radio options to the options attribute. |
lightning-select | Pass in the label and value that describe an option to the options attribute. |
lightning-tree | Pass in the tree items to the items attribute. |
The flatter structure in a base component is made possible by using an attribute to pass in configuration information and data. For more information, see Pass Configuration and Data to a Base Component.
As you build with base components and create your own components, it’s helpful to understand the use cases for composition vs flat structures.
If you end up with a heavily composed structure, consider moving the logic from child components back to a parent component. Doing so allows your parent component to inline as many of the elements, which improves performance by avoiding the rendering of more custom components where possible.
Keep in mind that the number of elements, functions, and event handlers increase component size and has performance implications especially when you are working with large numbers of such components on a page. If possible, move expensive operations higher up the component tree and reduce the number of operations a leaf component handles.
Additionally, consider these performance guidelines.
For frequently reused components, expensive operations impact performance exponentially. Here are several ways to reduce performance overhead.
j