Lightning App Builder Integration

Lightning App Builder allows administrators to build custom pages by dragging and dropping components. By exposing your Lightning Web Components in App Builder, you can make them configurable without requiring code changes.

Overview

To make a component available in Lightning App Builder, you need to:

Mark the component as exposed in the metadata file
Specify target contexts (App Page, Home Page, Record Page, etc.)
Define configurable properties using @api
Configure property types and options in the metadata

Basic Configuration

Component with @api Properties

compositionWithAppBuilder.js

import { LightningElement, api } from 'lwc';

export default class CompositionWithAppBuilder extends LightningElement {
    @api picklistValue;
    @api stringValue;
    @api numberValue;
}

compositionWithAppBuilder.html

<template>
    <lightning-card
        title="CompositionWithAppBuilder"
        icon-name="custom:custom57"
    >
        <div class="slds-var-m-around_medium">
            Properties from App Builder:
            <div class="slds-box slds-box_x-small">
                <p>picklistValue: {picklistValue}</p>
                <p>stringValue: {stringValue}</p>
                <p>numberValue: {numberValue}</p>
            </div>
        </div>
    </lightning-card>
</template>

Metadata Configuration

compositionWithAppBuilder.js-meta.xml

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle
    xmlns="http://soap.sforce.com/2006/04/metadata"
    fqn="compositionWithAppBuilder"
>
    <apiVersion>65.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__AppPage</target>
        <target>lightning__HomePage</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightning__AppPage, lightning__HomePage">
            <property
                name="picklistValue"
                type="String"
                datasource="Option One, Option Two, Option Three"
            />
            <property
                name="stringValue"
                type="String"
                placeholder="Type something here..."
            />
            <property
                name="numberValue"
                type="Integer"
                min="0"
                max="100"
                default="10"
            />
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>

Metadata Elements

Required Elements

Set isExposed to true

This makes the component visible in App Builder’s component palette

<isExposed>true</isExposed>

Define targets

Specify where the component can be used

<targets>
    <target>lightning__AppPage</target>
    <target>lightning__HomePage</target>
    <target>lightning__RecordPage</target>
</targets>

Configure properties

Define which properties are configurable and their input types

<targetConfigs>
    <targetConfig targets="lightning__AppPage">
        <property name="title" type="String" />
    </targetConfig>
</targetConfigs>

Available Targets

Target	Description
`lightning__AppPage`	Custom app pages
`lightning__HomePage`	Home pages
`lightning__RecordPage`	Record detail pages
`lightning__Tab`	Custom tabs
`lightningCommunity__Page`	Experience Cloud pages
`lightningCommunity__Default`	Experience Cloud themes

Property Types

App Builder supports various property types for configuration:

String

Simple text input:

<property
    name="stringValue"
    type="String"
    label="Text Input"
    description="Enter any text value"
    placeholder="Type something here..."
    default="Default value"
/>

String with Picklist

Dropdown selection using datasource:

<property
    name="picklistValue"
    type="String"
    label="Select Option"
    datasource="Option One, Option Two, Option Three"
    default="Option One"
/>

Integer

Numeric input with optional min/max constraints:

<property
    name="numberValue"
    type="Integer"
    label="Number"
    description="Enter a number between 0 and 100"
    min="0"
    max="100"
    default="10"
/>

Boolean

Checkbox input:

<property
    name="showDetails"
    type="Boolean"
    label="Show Details"
    default="true"
/>

Additional Types

Type	Use Case	Example
`Color`	Color picker	Background colors, themes
`Date`	Date selector	Default date values
`DateTime`	Date and time selector	Appointment times
`Object`	Complex object selector	Record IDs, references

Property Attributes

Common Attributes

<property
    name="propertyName"           <!-- JavaScript property name -->
    type="String"                 <!-- Data type -->
    label="Display Label"         <!-- Label shown in App Builder -->
    description="Help text"       <!-- Tooltip description -->
    default="Default value"       <!-- Default value -->
    required="true"               <!-- Make field required -->
    placeholder="Placeholder"     <!-- Input placeholder text -->
/>

Type-Specific Attributes

String with datasource:

<property
    name="picklistValue"
    type="String"
    datasource="Value1, Value2, Value3"
/>

Integer with constraints:

<property
    name="numberValue"
    type="Integer"
    min="0"
    max="100"
/>

Using Component Properties

Once configured in App Builder, the property values are automatically passed to your component:

import { LightningElement, api } from 'lwc';

export default class MyComponent extends LightningElement {
    @api title;
    @api showDetails;
    @api maxItems;
    
    get displayTitle() {
        return this.title || 'Default Title';
    }
    
    connectedCallback() {
        console.log('Max items:', this.maxItems);
    }
}

<template>
    <lightning-card title={displayTitle}>
        <template lwc:if={showDetails}>
            <!-- Detailed view -->
        </template>
    </lightning-card>
</template>

Best Practices

Provide sensible defaults

Always set default values so the component works out-of-the-box

<property
    name="maxRecords"
    type="Integer"
    default="10"
/>

Use clear labels and descriptions

Help administrators understand what each property does

<property
    name="showAvatar"
    type="Boolean"
    label="Show User Avatar"
    description="Display profile pictures next to user names"
/>

Validate property values

Don’t assume properties will always be valid

@api maxItems;

get validatedMaxItems() {
    const value = parseInt(this.maxItems, 10);
    return (value > 0 && value <= 100) ? value : 10;
}

Group related properties

Use consistent naming and organize properties logically

<!-- Display settings -->
<property name="showTitle" type="Boolean" />
<property name="showDescription" type="Boolean" />
<property name="showImage" type="Boolean" />

<!-- Behavior settings -->
<property name="enableAutoRefresh" type="Boolean" />
<property name="refreshInterval" type="Integer" />

Testing in App Builder

Deploy your component

Push the component and metadata to your org

sf project deploy start

Open Lightning App Builder

Navigate to Setup > Lightning App Builder

Create or edit a page

Choose the appropriate page type matching your target configuration

Find your component

Look for your component in the Custom components section

Drag and configure

Drag the component onto the page and test the property inputs

Save and activate

Save your page and activate it for users

Advanced: Object and Record Context

For Record Pages, you can access the current record’s context:

<targetConfigs>
    <targetConfig targets="lightning__RecordPage">
        <objects>
            <object>Contact</object>
            <object>Account</object>
        </objects>
    </targetConfig>
</targetConfigs>

import { LightningElement, api } from 'lwc';

export default class RecordPageComponent extends LightningElement {
    @api recordId;      // Automatically populated
    @api objectApiName; // Automatically populated
}

When using lightning__RecordPage, the recordId and objectApiName properties are automatically provided by the framework.

Get Started

Basics

Component Composition

Event Handling

Data Access

Component Features

Navigation

Styling

Advanced Topics

Guides

Overview

Basic Configuration

Component with @api Properties

Metadata Configuration

Metadata Elements

Required Elements

Available Targets

Property Types

String

String with Picklist

Integer

Boolean

Additional Types

Property Attributes

Common Attributes

Type-Specific Attributes

Using Component Properties

Best Practices

Testing in App Builder

Advanced: Object and Record Context

Next Steps

Composition Overview

Wire Service

​Overview

​Basic Configuration

​Component with @api Properties

​Metadata Configuration

​Metadata Elements

​Required Elements

​Available Targets

​Property Types

​String

​String with Picklist

​Integer

​Boolean

​Additional Types

​Property Attributes

​Common Attributes

​Type-Specific Attributes

​Using Component Properties

​Best Practices

​Testing in App Builder

​Advanced: Object and Record Context

​Next Steps

Composition Overview

Wire Service

Overview

Basic Configuration

Component with @api Properties

Metadata Configuration

Metadata Elements

Required Elements

Available Targets

Property Types

String

String with Picklist

Integer

Boolean

Additional Types

Property Attributes

Common Attributes

Type-Specific Attributes

Using Component Properties

Best Practices

Testing in App Builder

Advanced: Object and Record Context

Next Steps