Lightning Aura Components Developer Guide

Introducing Aura Components
Quick Start
Creating Components
Using Components
Aura Component Bundle Design Resources
Use Aura Components in Lightning Experience and the Salesforce Mobile App
Navigate Across Your Apps with Page References
Get Your Aura Components Ready to Use on Lightning Pages
Use Aura Components in Experience Builder
Use Aura Components with Flows
Add Components to Apps
Integrate Your Custom Apps into the Chatter Publisher
Using Background Utility Items
Use Lightning Components in Visualforce Pages
Use Aura and Lightning Web Components Outside of Salesforce with Lightning Out (Beta)
Lightning Container
Communicating with Events
Communicating Across the DOM with Lightning Message Service
Creating Apps
Styling Apps
Developing Secure Code
Using JavaScript
Working with Salesforce Data
Testing Components
Debugging
Performance
Reference
PDF

Aura Component Bundle Design Resources

Use a design resource to control which attributes are exposed to builder tools like the Lightning App Builder, Experience Builder, or Flow Builder. A design resource lives in the same folder as your .cmp resource, and describes the design-time behavior of the Aura component—information that visual tools need to display the component in a page or app.
For example, here’s a simple design resource that goes in a bundle with a “Hello World” component. We’ll build on this example as we move through the supported tags and attributes.
1<design:component label="Hello World">
2    <design:attribute name="subject" label="Subject" description="Name of the person you want to greet" />
3    <design:attribute name="greeting" label="Greeting" />
4</design:component>

design:component

This is the root element for the design resource. It contains the component’s design-time configuration for tools such as the App Builder to use.

Attribute Description
label Sets the label of the component when it displays in tools such as App Builder.

When creating a custom Lightning page template component, this text displays as the name of the template in the Lightning App Builder new page wizard.

Label expressions in markup are supported in .cmp and .app resources only.

Note

design:attribute

To make an Aura component attribute available for admins to edit in tools such as the App Builder, add a design:attribute node for the attribute into the design resource. An attribute marked as required in the component definition automatically appears, unless it has a default value assigned to it.

For Lightning page interfaces, the design resource supports only attributes of type Integer, String, or Boolean. To see which attribute types the lightning:availableForFlowScreens interface supports, go to Which Custom Lightning Component Attribute Types Are Supported in Flows?.

In a design:attribute node, Flow Builder supports only the name, label, description, and default attributes. The other attributes, like min and max, are ignored.

Note

Attribute Description
aiDescription AI-related description of the attribute, used by Agentforce to help analyze the component. Supported only in orgs that have Setup with Agentforce enabled.
datasource Renders a field as a picklist, with static values. Only supported for String attributes.
1<design:attribute name="Name" datasource="value1,value2,value3" />

You can also set the picklist values dynamically using an Apex class. See Create Dynamic Picklists for Your Custom Components for more information.

Any String attribute with a datasource in a design resource is treated as a picklist.
default Sets a default value on an attribute in a design resource.
1<design:attribute name="Name" datasource="value1,value2,value3" default="value1" />
description Displays as an i-bubble for the attribute in the tool.
label Attribute label that displays in the tool.
max If the attribute is an Integer, this sets its maximum allowed value. If the attribute is a String, this is the maximum length allowed.
min If the attribute is an Integer, this sets its minimum allowed value. If the attribute is a String, this is the minimum length allowed.
name Required attribute. Its value must match the aura:attribute name value in the .cmp resource.
placeholder Input placeholder text for the attribute when it displays in the tool.
required Denotes whether the attribute is required. If omitted, defaults to false.
type The design attribute’s data type. Color is the only valid value.

The Color type displays a color picker in Experience Builder. Applies only to components that implement the forceCommunity:availableForAllPageTypes interface.

Supported only for aura:attribute elements of type String in the .cmp resource.

Use the default attribute to specify RGBA, RGB, or hex strings. For example:

1<design:attribute type="Color" name="buttonColor" default="rgba(0, 255, 255, 1)" />

Label expressions in markup are supported in .cmp and .app resources only.

Note

<design:suppportedFormFactors> and <design:suppportedFormFactor>

Use these tag sets to designate which devices your component supports. The design:suppportedFormFactor subtag supports the type attribute. Valid type values are Large (desktop) and Small (phone).

If you don’t declare form factor support for a component, then by default, it supports the same form factors as the page types that it’s assigned to. App and record pages support the Large and Small form factors. Home pages support only the Large form factor.

Components on app and record pages can render on both mobile and desktop because those pages support both phone and desktop. Components on Home pages can render only on desktop because Home pages are supported only for desktop.

If you have an app or record page—which support both desktop and phone—you can use design:suppportedFormFactor to configure a component to render only when the page is viewed on a particular device. For example, if you restrict form factor support for your app page component to Small, the app page drops the component when the page is viewed on desktop. The app page displays the component when the page is viewed on a phone.

Here’s the “Hello World” component design resource, with both desktop and phone support added.
1<design:component label="Hello World">
2    <design:attribute name="subject" label="Subject" description="Name of the person you want to greet" />
3    <design:attribute name="greeting" label="Greeting" />
4    <design:supportedFormFactors>
5        <design:supportedFormFactor type="Large"/>
6        <design:supportedFormFactor type="Small"/>
7    </design:supportedFormFactors>
8</design:component>

You can add this tag set to your component design file to create custom page templates that support only desktop, only phone, or both.

<sfdc:objects> and <sfdc:object>

Use these tag sets to restrict your component to one or more objects.

<sfdc:objects> and <sfdc:object> aren’t supported in Experience Builder or the Flow Builder. They’re also ignored when setting a component to use as an object-specific action or to override a standard action.

Note

Here’s the same “Hello World” component’s design resource restricted to two objects.
1<design:component label="Hello World">
2    <design:attribute name="subject" label="Subject" description="Name of the person you want to greet" />
3    <design:attribute name="greeting" label="Greeting" />
4    <design:supportedFormFactors>
5        <design:supportedFormFactor type="Large"/>
6        <design:supportedFormFactor type="Small"/>
7    </design:supportedFormFactors>
8    <sfdc:objects>
9        <sfdc:object>Custom__c</sfdc:object>
10        <sfdc:object>Opportunity</sfdc:object>
11    </sfdc:objects>
12</design:component>

If an object is installed from a package, add the namespace__ string to the beginning of the object name when including it in the <sfdc:object> tag set. For example: objectNamespace__ObjectApiName__c.

These tag sets don't support external objects.

See the User Interface API Developer Guide for the list of supported objects.

<design:ai> and <design:description>

Use these tag sets to add an AI description to your component and make it accessible to Agentforce in Setup. Supported only for record pages in orgs that have Setup with Agentforce enabled.

In Setup, Agentforce can analyze and recommend custom components when creating a new Lightning page as a result of a user utterance. For Agentforce to analyze if your custom component fits the requirements outlined in the user’s utterance, your component must contain an AI-related description of what it does as well as descriptions of its attributes.

These descriptions aren't user-facing. Agentforce uses them as part of its analysis of the component for inclusion in agent-generated Lightning pages. AI component descriptions can be up to 4,000 characters. See Tips for Writing AI Component Descriptions in the Lightning Web Components Developer Guide.

Specify the design:ai tag only once inside a .design file. The design:ai tag contains one design:description tag.

To add an AI-related property description, use the aiDescription attribute on the design:attribute tag.

Here’s the same “Hello World” component with AI-related component and attribute descriptions.

1<design:component label="Hello World">
2    <design:attribute name="subject" label="Subject" description="Name of the person you want to greet"/>
3    <design:attribute name="greeting" label="Greeting"/>
4    <design:supportedFormFactors>
5        <design:supportedFormFactor type="Large"/>
6        <design:supportedFormFactor type="Small"/>
7    </design:supportedFormFactors>
8    <sfdc:objects>
9        <sfdc:object>Custom__c</sfdc:object>
10        <sfdc:object>Opportunity</sfdc:object>
11    </sfdc:objects>
12    <design:ai>
13        <design:description>This component displays a greeting that's addressed to the name in the subject property.
14        </design:description>
15   </design:ai>
16   <design:attribute name="myAttributeName" aiDescription="AI property description"/>
17</design:component>