# developer Lightning Types Developer Guide (lightning-type-systems) - Full Documentation
# Add and Modify Lightning Types in Setup
Manage your custom and standard Lightning types in Setup, whether they’re object-based types defined in JSON or Apex-based types referenced from a class. You can also verify that your LightningTypeBundle metadata deployed successfully.
From Setup, in the Quick Find box, enter `Lightning Types` and select **Lightning Types**.
![The Lightning Types page shows a list of Lightning types in your org. The Source column indicates whether a Lightning type is standard or custom.](https://developer.salesforce.com/docs/media/lightning-types-images/258-Updated-Setup-UI.png '{"class": "image-framed"}')
- Click a label to view its schema definition, namespace, and configuration details.
- To create a type, click **New Lightning Type**.
- To confirm that a LightningTypeBundle metadata deployed successfully, check the list on the **Lightning Types** page. Use the **Source** column to distinguish between Standard and Custom types.
**See Also**
- [_Salesforce Help_: Create a Custom Lightning Type](https://help.salesforce.com/s/articleView?id=platform.lt_intro.htm&type=5)
# Apex-Based Custom Lightning Types
With Apex-based custom Lightning types, you can define the structure of a custom Lightning type by referencing an Apex class code. Instead of manually defining every field and property in a JSON schema, the custom Lightning type inherits its structure directly from the Apex class member variables, specifically the variables annotated with `@AuraEnabled`. Use this approach when your agent action returns complex data that you have already modeled in your Apex logic. This method maintains a single source of truth for the data structure.
**Supported in**:
- Agentforce Employee agent in Lightning Experience
- Agentforce Service agent via Enhanced Chat v2
- Agentforce Employee agent on Mobile (iOS and Android)
- Agentforce Service agent via Enhanced Chat v2 on Mobile (iOS and Android)
**note:** Apex-based types aren’t supported in Experience Builder sites.
## Schema.json for Apex-Based Custom Lightning Types
For Apex-based types, the schema references an Apex class. You don’t define properties here. Instead, you point to the class that contains the data structure.
This table lists the keywords that you can specify in a `schema.json` file.
| Keyword | Required or Optional | Type | Description |
| ---------------- | -------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title` | Required | String | Name for the Lightning type |
| `description` | Optional | String | Description for the Lightning type |
| `lightning:type` | Required | String | Refers to `@apexClassType` types by using fully qualified names
This keyword is syntactic sugar for the `$ref` keyword in JSON Schema, which links together schemas.
For information about `$ref`, see [Understanding JSON Schema: The Sref keyword](https://json-schema.org/understanding-json-schema/structuring?highlight=ref#ref) |
Unless noted otherwise, the keywords follow the JSON Schema specification.
Here’s a sample code that shows the contents of the `schema.json` file for a custom Lightning type `flightResponse`.
```json
{
"title": "My Flight Response",
"description": "My Flight Response",
"lightning:type": "@apexClassType/c__AvailableFlight"
}
```
**See Also**
- [Create Custom Labels for Custom Lightning Types](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-core.md#create-custom-labels-for-custom-lightning-types)
### Apex Class Requirements
To ensure successful invocation and rendering within Agentforce—especially in namespaced orgs or managed packages—configure your Apex classes according to these requirements.
**Class Definition and Visibility**
- **Top-level definition**. Define every class as a top-level class in its own file. Don’t use nested (inner) classes.
- **Global visibility**. Mark all classes as `global`. Using `public` or `private` modifiers can cause failures in namespaced orgs or managed packages.
**Annotations**
- **@AuraEnabled**. Apply this annotation to every field required in the response, including fields inside objects used as `@InvocableVariable`.
- **@JsonAccess**. Annotate every class with `@JsonAccess(serializable='always' deserializable='always')`. This annotation ensures that the internal invocation layer can process the data.
**Namespace Prefixes**
- **Local org classes**. Use the “c” prefix for classes in your local org.
- **Managed packages**. Use the specific registered namespace for the package.
See [Understand Namespace Prefixes for Metadata References](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-core.md#understand-namespace-prefixes-for-metadata-references)
**Supported Types**
Not all data types that you use in an Apex class are supported in Lightning types.
Lightning types support these data types.
- Primitives, including Integer, Double, Long, Date, Datetime, Time, String, ID, and Boolean
- sObjects, either a generic or specific sObject, such as Account, Contact, and MyCustomObject\_\_c
- Collections
- A list or array of primitives, sObjects, user-defined Apex classes, and collections
- A map, represented as `Map`, where the key is always a string and the value can be a primitive, sObject, or collection
- User-defined Apex classes
**important:** If you created an agent action before meeting these requirements, delete and recreate the agent action after updating the Apex classes. This step correctly registers the changes.
### Schema Projection
Schema projection is the automated process that evaluates an Apex class to generate a runtime JSON schema.
**How It Works**
- **API Evaluation**. The internal [LightningTypeBundle](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_lightningtypebundle.htm) API introspects the referenced Apex class. The projection process scans for the `@AuraEnabled` annotation on member variables to determine which properties to expose.
- **Dynamic Translation**. The projection layer automatically translates Apex primitives (such as String and Integer) and complex types (such as nested classes or sObjects) into the corresponding Lightning type schema. This automation eliminates manual variable mapping.
- **Single Source of Truth**. Because the schema projects directly from the code, changes to the Apex class automatically update the Lightning type’s structure. This automation eliminates manual updates to the `schema.json` file.
## UI Configuration for Apex-Based Custom Lightning Types
While `schema.json` defines the data structure, the UI configuration files in the Lightning Type Bundle control the visual representation. Organize these files by channel to support specific Salesforce applications.
[**Channels**](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.md#channels)
Store UI overrides in channel-specific subfolders to target different Salesforce applications.
- **lightningDesktopGenAi**. Use this folder for Agentforce Employee agents in Lightning Experience.
- **enhancedWebChat**. Use this folder for Agentforce Service agents via Enhanced Chat v2.
- **lightningMobileGenAi**. Use this folder for Agentforce Employee agents on Mobile (iOS and Android) and Agentforce Service agents via Enhanced Chat v2 on Mobile (iOS and Android).
[**Configuration Files**](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.md#ui-configuration-files)
Configure input and output UI overrides by using these JSON files.
- **editor.json**. Configures the UI when the custom Lightning type is an input parameter. It points to a Lightning Web Component (LWC) that serves as a custom form for data entry.
- **renderer.json**. Configures the UI when the custom Lightning type is an output parameter. It points to an LWC that renders the returned data (for example, as a custom card or list).
[**Component Override**](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.md#component-override)
You can customize the visual presentation by adding component overrides to your `editor.json` and `renderer.json` files.
- **Top-Level Override**. A top-level override replaces the default UI for the entire custom Lightning type. To configure this override, use the `$` symbol as the key in the `componentOverrides` section of your `editor.json` or `renderer.json`. This approach is useful for creating specialized interfaces, such as a custom card or a multi-property form handled by a single component.
[**Attribute Mapping**](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.md#lightning-web-component-attribute-mapping)
In both configuration files, map schema properties to LWC component properties by using the `{!$attrs.PropertyName}` syntax.
**note:** For a complete list of supported channels and detailed JSON syntax, see [Lightning Type UI Configuration](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.md).
**LWC Target Requirements**
To use a component as an override, include the appropriate target in the component’s `js-meta.xml` file.
- [`lightning__AgentforceInput`](https://developer.salesforce.com/docs/platform/lwc/guide/targets-lightning-agentforce-input.html) for input overrides
- [`lightning__AgentforceOutput`](https://developer.salesforce.com/docs/platform/lwc/guide/targets-lightning-agentforce-output.html) for output overrides
**See Also**
- [Lightning Types Configuration Files](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-core.md#lightning-types-configuration-files)
- [Lightning Type UI Configuration](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.md)
## Apex Class Modification Guidelines
To maintain the integrity of active agent actions and prevent runtime failures, adhere to these restrictions when you modify Apex classes referenced by a custom Lightning type.
| Change Type | Status | Impact |
| -------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------- |
| Additive Changes | Permitted | Adding new `@AuraEnabled` fields to an existing class is safe. Schema projection picks up these changes automatically. |
| Class Renaming or Deletion | Prohibited | Renaming or deleting an Apex class that a `lightning:type` schema references causes runtime failures. |
| Data Type Changes | Breaking | Changing a variable’s type, for example, from `Integer` to `String`, breaks the integration. |
| Field Removal | Breaking | Removing an `@AuraEnabled` field that an agent action uses causes invocation errors. |
| Visibility Downgrade | Prohibited | Changing a class from `global` to `public` in a managed package breaks external references. |
# Core Concepts of Custom Lightning Types
You build all custom Lightning types, whether Apex-based or object-based, by using a common set of foundational components. Understand these core concepts to create, customize, and deploy your types.
## Building Blocks of a Lightning Type
Lightning Type consists of these artifacts.
- **Schema** defines the data structure and the rules for its validation, such as maximum length, type, and format.
- **Editor** defines the input UI component that you use to enter or edit data.
- **Renderer** defines the output UI component that displays data.
## LightningTypeBundle Metadata Type
The LightningTypeBundle metadata type describes the custom Lightning types. It’s available in API version 64.0 and later.
To get a list of the custom and standard Lightning types deployed in your org, make a call to the [`/connect/lightning-types`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_lightning_types.htm) resource.
For more information about the resources available in the Type System Connect REST API, see the [Type System Resources](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_type_system_resources.htm).
## Understand the LightningTypeBundle Structure
LightningTypeBundle components are stored in the lightningTypes folder.
Here’s an example of the LightningTypeBundle structure.
```
+--myMetadataPackage
+--lightningTypes (1)
+--TYPE_NAME (2)
+--schema.json (3)
+--CHANNEL_NAME (4)
+--editor.json (5) OR +--renderer.json (6)
```
The bundle includes these resources.
- The `lightningTypes` folder (1) contains a folder for each custom Lightning type created in the format `{typeName}` (2).
- Each custom Lightning type folder contains a [`schema.json`](#lightning-types-configuration-files) file (3) that defines the JSON schema that drives the custom Lightning type validation.
- Optional channel-specific folders (4). To override the default UI for a specific Salesforce application, the bundle contains a folder named after that channel. The supported channel folders are:
- `lightningDesktopGenAi` (Agentforce Employee agent in Lightning Experience)
- `enhancedWebChat` (Agentforce Service agent via Enhanced Chat v2)
- `lightningMobileGenAi` (Agentforce Employee agent on Mobile and Agentforce Service agent via Enhanced Chat v2 on Mobile)
- `experienceBuilder` (Experience Builder)
Inside the `{channelName}` folder, you can configure:
- The [`editor.json`](#lightning-types-configuration-files) file (5) containing custom user interface and editor information
- The [`renderer.json`](#lightning-types-configuration-files) file (6) containing custom user interface and renderer information
**note:** This file isn’t supported in `experienceBuilder`.
### Lightning Type Structure for HXL Widgets (Beta)
When you reference a widget in a custom Lightning type, create a `renderer.json` file at the root level (parallel to `schema.json`) without channel-specific folders. Don't add an `editor.json` file or a channel subfolder.
```
+--myMetadataPackage
+--lightningTypes
+--TYPE_NAME
+--schema.json
+--renderer.json
```
For details about widgets, see [Build Rich UI Experiences with HXL Widgets](https://developer.salesforce.com/docs/platform/hxl/guide/hxl-rich-ui.html).
### Use SF Commands or Metadata API to Deploy LightningTypeBundles
To deploy a LightningTypeBundle to your Salesforce org, use Metadata API or SF Commands. The Metadata API uses a manifest file that defines the metadata that you want to deploy.
Here’s an example `package.xml` manifest file for a LightningTypeBundle that includes the custom Lightning type `myFlight`.
```xml
myFlight
LightningTypeBundle
64.0
```
To delete a custom Lightning type, you must deploy a destructiveChanges package to your org that lists the types to delete.
**See Also**
- _Metadata API Developer Guide_: [Deploying and Retrieving Metadata with the Zip File](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/file_based_zip_file.htm)
- _Metadata API Developer Guide_: [Deleting Components from an Organization](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_deploy_deleting_files.htm)
### SF Commands and Packaging Support
Use the Salesforce CLI `project` commands to deploy, retrieve, and track the source files for the LightningTypeBundle metadata type in your Salesforce DX project. See [project Commands](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_project_commands_unified.htm#cli_reference_project_commands_unified) in the Salesforce CLI Command Reference.
Packaging supports the LightningTypeBundle metadata type that describes custom Lightning types. You can include the LightningTypeBundle in first-generation (1GP) and second-generation (2GP) packages. See the [First-Generation Managed Packaging Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.pkg1_dev.meta/pkg1_dev/first_gen_packageable_components.htm#mdc_lightning_types) and the [Second-Generation Managed Packaging Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.pkg2_dev.meta/pkg2_dev/packaging_packageable_components.htm#mdc_lightning_types).
**See Also**
- [Metadata Coverage Report](https://developer.salesforce.com/docs/metadata-coverage/64)
- [Salesforce CLI Command Reference](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_top.htm)
- [Use Managed Packages to Develop Your AppExchange Solution](https://developer.salesforce.com/docs/atlas.en-us.packagingGuide.meta/packagingGuide/managed_packaging_intro.htm)
## Lightning Types Configuration Files
The LightningTypeBundle includes these configuration files.
**Schema.json**
The `schema.json` file is a required resource in every Lightning Type Bundle. It defines the data structure, validation rules (such as type, format, and maximum length), and constraints for your custom Lightning type by using the JSON Schema specification.
**Editor.json**
With the optional `editor.json` file, you can override the default input UI. Use this file to define the specific custom LWC component for entering or editing data.
The `editor.json` file supports this type of override.
- **Editor Override**. Defines the custom editor for the custom Lightning type. Use the `$` keyword to specify an LWC component that captures or edits data for the entire type. Alternatively, use property names to specify LWC components that capture or edit data for individual properties while default editors handle the rest.
**Renderer.json**
With the optional `renderer.json` file, you can override the default output UI. Use this file to define the custom LWC component used to present or display data to the user.
The `renderer.json` file supports two types of overrides.
- **Renderer Override**. Defines a single renderer for the entire custom Lightning type. You use the `$` keyword to specify the LWC component that renders the data for a single instance of the type.
- **Collection Renderer Override**. Defines a renderer for a structured list or array of data. This approach uses the `collection` keyword to associate a custom LWC component that renders the entire list of data at once.
**See Also**
- [Component Override](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.md#component-override)
## Understand Namespace Prefixes for Metadata References
When you reference metadata such as a custom label or a component in your custom Lightning type, use the correct namespace prefix. This prefix applies to metadata references in your schema, editor, and renderer files.
**For metadata created in your org**
Use the “c” namespace prefix. This rule applies even if your org has its own namespace. For example, if your org’s namespace is `myOrgNamespace` and you create an LWC component named `flightDetails`, refer to it as `c/flightDetails`.
**note:** This rule also applies to custom Lightning types in managed packages. Reference any new metadata in the same package by using the “c” prefix.
**For metadata installed via a managed package**
Use the package’s unique namespace as the prefix. For example, if a package has the namespace `isv` and includes an LWC component named `flightDetails`, refer to it as `isv/flightDetails`.
**Example of Local Org Metadata References**
This `schema.json` file uses the “c” namespace to reference a custom label and the `@apexClassType` reference of an Apex class.
```json
{
"title": "{!$Label.c.FlightTitle}",
"description": "My Flight Response",
"lightning:type": "@apexClassType/c__AvailableFlight"
}
```
This `renderer.json` file uses the “c” namespace to reference a Lightning Web Component.
```json
{
"renderer": {
"componentOverrides": {
"$": {
"definition": "c/flightDetails"
}
}
}
}
```
## Create Custom Labels for Custom Lightning Types
You can customize labels for the title and description values in the `schema.json` file for a custom Lightning type.
To create and use a translated custom label in a custom Lightning type, complete these steps.
1. From Setup, enter `Labels` in the Quick Find box, and then select **Custom Labels**.
2. Create a custom label.
3. In the `schema.json` file for the custom Lightning type that you created, use the expression `{!$Label.c.MyLabel1}` for the title and description values. Here, “c” is the namespace prefix and “MyLabel1” is the API name of the custom label.
**See Also**
- [Create and Edit Custom Labels](https://help.salesforce.com/s/articleView?id=platform.cl_edit.htm&type=5)
- [Translate Custom Labels](https://help.salesforce.com/s/articleView?id=platform.cl_translate_edit.htm&type=5)
## Salesforce Applications That You Can Override
You can override the default UI of some Salesforce applications by using a custom Lightning type. Each Salesforce application listens to a specific channel that you specify in your [LightningTypeBundle](#understand-the-lightningtypebundle-structure).
You can override these Salesforce applications.
- Agentforce Employee agent in Lightning Experience
- Agentforce Service agent via Enhanced Chat v2
- Agentforce Employee agent on Mobile (iOS and Android)
- Agentforce Service agent via Enhanced Chat v2 on Mobile (iOS and Android)
- Experience Builder
- Prompt Builder
- Flows via Structured Outputs
To override the UI, create a folder in your LightningTypeBundle with the application’s corresponding channel name.
| Salesforce Application | Channel Folder | Category |
| ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | -------- |
| Agentforce Employee agent in Lightning Experience | `lightningDesktopGenAi` | Apex |
| Agentforce Service agent via Enhanced Chat v2 | `enhancedWebChat` | Apex |
| Agentforce Employee agent on Mobile (iOS and Android)
Agentforce Service agent via Enhanced Chat v2 on Mobile (iOS and Android) | `lightningMobileGenAi` | Apex |
| Experience Builder | `experienceBuilder` | Object |
| Prompt Builder | Not Applicable | Object |
| Flows via Structured Outputs | Not Applicable | Object |
**See Also**
- [Channels](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.md#channels)
- [_Agentforce Developer Guide_: Custom Lightning Type Examples](https://developer.salesforce.com/docs/ai/agentforce/guide/lightning-types-examples.html)
- [_Lightning Web Components Developer Guide_: Overview: Creating Custom Property Types and Editors](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-overview-custom-property-types.html)
- [_Salesforce Help_: Build and Manage Lightning Types for Prompt Templates](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_build_manage_lt.htm&type=5)
- [_Salesforce Help_: Flow Core Action: AI Agent Actions](https://help.salesforce.com/s/articleView?id=platform.automate_flow_ref_elements_actions_generate_ai_agent_response.htm&type=5)
- [_Salesforce Help_: Custom Lightning Types in the Salesforce Mobile App](https://help.salesforce.com/s/articleView?id=sf.salesforce_app_clt_mobile.htm&type=5)
# Define a Property-Level Editor Override
You can define a specific editor for an individual property within your custom Lightning type in the `editor.json` file. This editor applies only to the specified property, while default editors continue to handle the remaining properties.
For example, you have a custom Lightning type named `contactType` with two properties: `firstName` and `lastName`. You want to use a custom input component to handle the `lastName` property (perhaps to add specific validation or styling), while the default text editor handles the `firstName`.
Here’s an example of what the `editor.json` file organization looks like for the custom Lightning type `contactType`.
```
+--lightningTypes
+--contactType
+--schema.json
+--experienceBuilder
+--editor.json
```
**Example: Configuration Using Property Names**
This example shows you how to configure a component to handle a specific property. The component receives only the value for that property via an `@api` value property.
1. **Define the schema.json file.**
This schema defines the data structure. It defines a `firstName` and `lastName` property, but you override only the `lastName`.
```json
{
"title": "Contact Type",
"description": "Contact of a Person",
"lightning:type": "lightning__objectType",
"properties": {
"firstName": {
"title": "First Name",
"description": "First Name of person",
"lightning:type": "lightning__textType",
"maxLength": 50
},
"lastName": {
"title": "Last Name",
"description": "Last name of person",
"lightning:type": "lightning__textType",
"maxLength": 50
}
},
"required": ["firstName", "lastName"]
}
```
2. **Create the LWC Bundle.**
Create a custom Lightning Web Component (such as `c/customLastNameInput`) to handle the specific property.
The `customLastNameInput.html` template binds the standard input component to your custom logic.
```html
```
The `customLastNameInput.js` file handles the data flow. The component exposes public properties—such as `value`, `label`, and `required`—to receive data. To capture the user's input, the component dispatches a `valuechange` event whenever the value updates.
```js
import { LightningElement, api } from "lwc";
export default class CustomLastNameInput extends LightningElement {
@api value; // Receives the current value of 'lastName'
@api label; // Receives the 'title' from the schema ("Last Name")
@api required; // Receives the required state (true)
@api disabled; // Handled by the panel (e.g., after submission)
handleChange(event) {
const newValue = event.detail.value;
// Notify the system that the value has changed
this.dispatchEvent(
new CustomEvent("valuechange", {
detail: {
value: newValue,
validity: event.target.checkValidity(), // Optional: pass validity state
},
}),
);
}
}
```
The `customLastNameInput.js-meta.xml` file exposes the component to the editor.
```xml
64.0
true
lightning__PropertyEditor
```
3. **Configure the editor.json file.**
Use the property name `lastName` as the key in the `componentOverrides` section.
Here’s how to reference `customLastNameInput` to override the editor in the `editor.json` file.
```json
{
"editor": {
"componentOverrides": {
"lastName": {
"definition": "c/customLastNameInput"
}
}
}
}
```
**Example: Layout Configuration**
If you're reusing an existing component and decide to use layouts, you can combine the `layout` and `componentOverrides` sections in the `editor.json` file. With this approach, you control the visual arrangement of properties while simultaneously assigning a specific custom component to handle the behavior of an individual property.
In this scenario, you arrange the `firstName` and `lastName` properties horizontally by using a layout, while specifically overriding the `lastName` property to use a reused custom component (`c/customLastNameInput`).
1. **Define the schema.json file.**
This schema defines the data structure. It defines a `firstName` and `lastName` property, but you override only the `lastName`.
```json
{
"title": "Contact Type",
"description": "Contact of a Person",
"lightning:type": "lightning__objectType",
"properties": {
"firstName": {
"title": "First Name",
"description": "First Name of person",
"lightning:type": "lightning__textType",
"maxLength": 50
},
"lastName": {
"title": "Last Name",
"description": "Last name of person",
"lightning:type": "lightning__textType",
"maxLength": 50
}
},
"required": ["firstName", "lastName"]
}
```
2. **Create the LWC Bundle.**
Create a custom Lightning Web Component (such as `c/customLastNameInput`) to handle the specific property.
The `customLastNameInput.html` template binds the standard input component to your custom logic.
```html
```
The `customLastNameInput.js` file handles the data flow. The component exposes public properties—such as `value`, `label`, and `required`—to receive data. To capture the user's input, the component dispatches a `valuechange` event whenever the value updates.
```js
import { LightningElement, api } from "lwc";
export default class CustomLastNameInput extends LightningElement {
@api value; // Receives the current value of 'lastName'
@api label; // Receives the 'title' from the schema ("Last Name")
@api required; // Receives the required state (true)
@api disabled; // Handled by the panel (e.g., after submission)
handleChange(event) {
const newValue = event.detail.value;
// Notify the system that the value has changed
this.dispatchEvent(
new CustomEvent("valuechange", {
detail: {
value: newValue,
validity: event.target.checkValidity(), // Optional: pass validity state
},
}),
);
}
}
```
The `customLastNameInput.js-meta.xml` file exposes the component to the editor.
```xml
64.0
true
lightning__PropertyEditor
```
3. **Configure the editor.json file.**
Use the property name `lastName` as the key in the `componentOverrides` section.
Here’s how to reference `customLastNameInput` to override the editor in the `editor.json` file.
```json
{
"editor": {
"componentOverrides": {
"lastName": {
"definition": "c/customLastNameInput"
}
},
"layout": {
"definition": "lightning/verticalLayout",
"children": [
{
"definition": "lightning/horizontalLayout",
"children": [
{
"definition": "lightning/propertyLayout",
"attributes": { "property": "firstName" }
},
{
// This will render the overridden c/customLastNameInput
// defined in componentOverrides above.
"definition": "lightning/propertyLayout",
"attributes": { "property": "lastName" }
}
]
}
]
}
}
}
```
**note:** When you use `lightning/propertyLayout` to place a property, the editor checks for a corresponding `componentOverrides` definition. If an override exists (such as in the `lastName` example), the custom component renders. Otherwise, the default input renders.
**See Also**
- [_Lightning Web Components Developer Guide_: Overview: Creating Custom Property Types and Editors](https://developer.salesforce.com/docs/platform/lwc/guide/use-experience-cloud-overview-custom-property-types.html)
# Define a Top-Level Collection Renderer Override
Associate a custom LWC for rendering structured lists of data.
For example, you have a custom Lightning type named `hotelResponse` that returns a list of hotels. You configure `renderer.json` to render the entire list of hotel data.
Here’s an example of what the `renderer.json` file can look like for the custom Lightning type `hotelResponse`.
```
+--lightningTypes
+--hotelResponse
+--schema.json
+--lightningDesktopGenAi
+--renderer.json
```
**important:** This example uses `lightningDesktopGenAi` to configure the custom Lightning type. Only specific channels support output overrides (`renderer.json`). Verify that your channel supports this feature before configuring the file.
**Example: Basic Configuration Using the value Property**
This example shows you how to configure a component to handle the entire object via a single `@api` value property. The component receives the list via the value property.
**note:** To view a complete, working example of an LWC collection renderer implementation, see [Customize UI for Output](https://developer.salesforce.com/docs/ai/agentforce/guide/lightning-types-example-collection-renderer.html#customize-ui-for-output).
1. [**Create the LWC**](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-introduction.html).
This sample code shows the LWC component `hotelDetails`.
```js
import { LightningElement, api } from "lwc";
export default class HotelDetails extends LightningElement {
@api value;
}
```
2. **Configure the renderer.json file.**
Use the `collection` key to specify that this override applies to lists.
Here’s how to reference `hotelDetails` to override the renderer for the `Hotel` output in the `renderer.json` file.
```json
{
"collection": {
"renderer": {
"componentOverrides": {
"$": {
"definition": "c/hotelDetails"
}
}
}
}
}
```
**See Also**
- [_Agentforce Developer Guide_: Custom Lightning Type Examples](https://developer.salesforce.com/docs/ai/agentforce/guide/lightning-types-examples.html)
- [_Salesforce Help_: Custom Lightning Types in the Salesforce Mobile App](https://help.salesforce.com/s/articleView?id=sf.salesforce_app_clt_mobile.htm&type=5)
# Define a Top-Level Editor Override
You can define a single editor for your entire custom Lightning type in the `editor.json` file. This editor applies whenever an instance of the type is used as an input parameter.
For example, you have a custom Lightning type named `taskFilter` that corresponds to the Apex class `TaskCriteria` with two properties: `priorityLevel` and `dueDate`. You want to use a custom dropdown to select the priority level and a calendar picker for the due date.
Here’s an example of what the `editor.json` file can look like for the custom Lightning type `taskFilter`.
```
+--lightningTypes
+--taskFilter
+--schema.json
+--lightningDesktopGenAi
+--editor.json
```
**note:** This example uses `lightningDesktopGenAi` to configure the custom Lightning type. To configure the type for a different channel, create the `editor.json` file inside the folder that corresponds to that channel.
**Example: Basic Configuration Using the value Property**
This example shows you how to configure a component to handle the entire object via a single `@api` value property. The component receives the full object in one property.
**note:** To view a complete, working example of an LWC editor implementation, see [Customize UI for Input](https://developer.salesforce.com/docs/ai/agentforce/guide/lightning-types-example-full-editor-renderer.html#customize-ui-for-input).
1. [**Create the LWC**](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-introduction.html).
This sample code shows the LWC component `myTaskComponent`.
```js
import { LightningElement, api } from "lwc";
export default class MyTaskComponent extends LightningElement {
// This property doesn’t accept inbound context or default values from the agent. Use it strictly to capture user input. The framework sends this data to the agent action only when the user submits the response in the chat interface.
@api value;
// Example: { priorityLevel: 'High', dueDate: '2026-05-15' }
// Add your custom UI event handlers here.
}
```
**note:** The `@api` value property in custom Lightning type editors doesn’t support data injection, so the agent can’t pre-populate it with conversational context or default values. Use it only to capture user input. The framework returns this data to the agent action only after the user submits a response in the chat interface.
2. **Update the js-meta.xml file.**
Include the [`lightning__AgentforceInput`](https://developer.salesforce.com/docs/platform/lwc/guide/targets-lightning-agentforce-input.html) target.
This sample code shows the contents of the `myTaskComponent.js-meta.xml` file.
```xml
64.0
true
My Task Component
lightning__AgentforceInput
```
3. **Configure the editor.json file.**
Use the `$` keyword to map the type to the component.
Here’s how to reference `myTaskComponent` to override the editor for the `taskFilter` custom Lightning type in the `editor.json` file.
```json
{
"editor": {
"componentOverrides": {
"$": {
"definition": "c/myTaskComponent"
}
}
}
}
```
**Example: Attribute Mapping**
If you’re reusing an existing component and the property names don't match your schema (for example, the component uses `urgency` instead of `priorityLevel`), you must map the properties.
1. **Create the LWC.**
This sample code shows `myExistingTaskComponent`.
```js
import { LightningElement, api } from "lwc";
export default class MyExistingTaskComponent extends LightningElement {
// The framework passes the mapped data into these properties.
// Expected value example: 'High'
@api urgency;
// Expected value example: '2026-05-15'
@api dueDate;
// Add your custom UI event handlers here.
}
```
2. **Update the js-meta.xml file.**
Expose the properties in `targetConfigs` to register them as valid input properties for the `lightning__AgentforceInput` target.
This sample code shows the contents of the `myExistingTaskComponent.js-meta.xml` file.
```xml
64.0
true
My Existing Task Component
lightning__AgentforceInput
```
3. **Configure the editor.json file with attribute mapping.**
Use the attributes object to link schema properties to component properties.
This sample code shows how to reference `myExistingTaskComponent` to override the editor for the `taskFilter` custom Lightning type in the `editor.json` file.
```json
{
"editor": {
"componentOverrides": {
"$": {
"definition": "c/myExistingTaskComponent",
"attributes": {
"urgency": "{!$attrs.priorityLevel}",
"dueDate": "{!$attrs.dueDate}"
}
}
}
}
}
```
**note:** You must map the component’s properties to the corresponding properties in the Apex class, even if they have the same name. However, if the component receives the entire Apex class object through a single value attribute, you don’t need to map the individual attributes.
The expression `"urgency": "{!$attrs.priorityLevel}"` links the `priorityLevel` property of the `TaskCriteria` Apex class to the `urgency` property of the LWC component `myExistingTaskComponent` (and vice versa).
Here’s what each element represents.
- `urgency`: Property in the LWC component `myExistingTaskComponent`
- `{!$attrs}`: Pointer to the `TaskCriteria` class
- `priorityLevel`: Property in the `TaskCriteria` class
- `{!$attrs.priorityLevel}`: Evaluates to the specific value of the `priorityLevel` property so it can be dynamically passed to the component
**See Also**
- [_Agentforce Developer Guide_: Custom Lightning Type Examples](https://developer.salesforce.com/docs/ai/agentforce/guide/lightning-types-examples.html)
- [_Salesforce Help_: Custom Lightning Types in the Salesforce Mobile App](https://help.salesforce.com/s/articleView?id=sf.salesforce_app_clt_mobile.htm&type=5)
# Define a Top-Level Renderer Override
You can define a single renderer for your entire custom Lightning type. The renderer applies whenever an instance of the type is returned as output.
For example, you have a custom Lightning type named `taskCard` that corresponds to an Apex class `TaskRecord` with four properties: `cardName`, `cardId`, `createdDate`, and `lastUpdate`. You want to display the data by using a custom task board card that visually highlights recently updated items.
Here’s an example of what the `renderer.json` file can look like for the custom Lightning type `taskCard`.
```
+--lightningTypes
+--taskCard
+--schema.json
+--lightningDesktopGenAi
+--renderer.json
```
**important:** This example uses `lightningDesktopGenAi` to configure the custom Lightning type. Only specific channels support output overrides (`renderer.json`). Verify that your channel supports this feature before configuring the file.
**Example: Basic Configuration Using the value Property**
This example shows you how to configure a component to handle the entire object via a single `@api` value property. The component receives the full object in one property.
**note:** To view a complete, working example of an LWC renderer implementation, see [Customize UI for Output](https://developer.salesforce.com/docs/ai/agentforce/guide/lightning-types-example-full-editor-renderer.html#customize-ui-for-output).
1. [**Create the LWC**](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-introduction.html).
This sample code shows the LWC component `myCardRenderer`.
```js
import { LightningElement, api } from "lwc";
export default class MyCardRenderer extends LightningElement {
// The framework populates this property with the output data to be displayed.
@api value;
// Example: { cardName: 'Review Q3 Metrics', cardId: 'TSK-00124', createdDate: '2026-04-20', lastUpdate: '2026-04-23' }
// Add your custom UI event handlers here.
}
```
2. **Update the js-meta.xml file.**
Include the [`lightning__AgentforceOutput`](https://developer.salesforce.com/docs/platform/lwc/guide/targets-lightning-agentforce-output.html) target.
This sample code shows the contents of the `myCardRenderer.js-meta.xml` file.
```xml
64.0
true
My Card Renderer
lightning__AgentforceOutput
```
3. **Configure the renderer.json file.**
Use the `$` keyword to map the type to the component.
Here’s how to reference `myCardRenderer` to override the renderer for the `taskCard` custom Lightning type in the `renderer.json` file.
```json
{
"renderer": {
"componentOverrides": {
"$": {
"definition": "c/myCardRenderer"
}
}
}
}
```
**Example: Attribute Mapping**
If you’re reusing an existing component and the property names don't match your schema (for example, the component uses `title` instead of `cardName`), you must map the properties.
1. **Create the LWC.**
This sample code shows `myExistingCardRenderer`.
```js
import { LightningElement, api } from "lwc";
export default class MyExistingCardRenderer extends LightningElement {
// The framework passes the mapped data into these properties.
// Expected value example: 'Review Q3 Metrics'
@api title;
// Expected value example: 'TSK-00124'
@api cardId;
// Expected value example: '2026-04-20'
@api createdDate;
// Expected value example: '2026-04-23'
@api lastUpdate;
// Add your custom UI event handlers here.
}
```
2. **Update the js-meta.xml file.**
Expose the properties in `targetConfigs` to register them as valid input properties for the `lightning__AgentforceOutput` target.
This sample code shows the contents of the`myExistingCardRenderer.js-meta.xml` file.
```xml
64.0
true
My Existing Card Renderer
lightning__AgentforceOutput
```
3. **Configure the renderer.json file with attribute mapping.**
Use the `attributes` object to link schema fields to component properties.
This sample code shows how to reference `myExistingCardRenderer` to override the renderer for the `taskCard` custom Lightning type in the `renderer.json` file.
```json
{
"renderer": {
"componentOverrides": {
"$": {
"definition": "c/myExistingCardRenderer",
"attributes": {
"title": "{!$attrs.cardName}",
"cardId": "{!$attrs.cardId}",
"createdDate": "{!$attrs.createdDate}",
"lastUpdate": "{!$attrs.lastUpdate}"
}
}
}
}
}
```
**note:** You must map the component’s properties to the corresponding properties in the Apex class, even if they have the same name. However, if the component receives the entire Apex class object through a single value attribute, you don’t need to map the individual attributes.
The expression `"title": "{!$attrs.cardName}"` links the `cardName` property of the `TaskRecord` Apex class to the `title` property of the LWC component `myExistingCardRenderer` (and vice versa).
Here’s what each element represents.
- `title`: Property in the LWC component `myExtistingCardRenderer`
- `{!$attrs}`: Pointer to the `TaskRecord` class
- `cardName`: Property in the `TaskRecord` class
- `{!$attrs.cardName}`: Evaluates to the specific value of the `cardName` property so it can be dynamically passed to the component
**See Also**
- [_Agentforce Developer Guide_: Custom Lightning Type Examples](https://developer.salesforce.com/docs/ai/agentforce/guide/lightning-types-examples.html)
- [_Salesforce Help_: Custom Lightning Types in the Salesforce Mobile App](https://help.salesforce.com/s/articleView?id=sf.salesforce_app_clt_mobile.htm&type=5)
# Get Started with Lightning Types
Lightning Types are JSON-based data types to structure, validate, and display data.
With Lightning Types, you can manage the representation and shape of data types. You can use Lightning types to create consistent and flexible data interactions.
Salesforce provides standard Lightning types, such as [text](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-references.md#lightning__texttype) and [multiline](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-references.md#lightning__multilinetexttype) text, to structure your data type. Additionally, you can create custom Lightning types to customize the UI experience based on your business requirements.
## Standard Lightning Types
Salesforce provides some Lightning types out of the box that act as the basic types that you can reference to structure a more complex schema.
To understand how a Lightning type is validated, you must identify the underlying type used for each Lightning type.
Each standard Lightning type includes a default editor and renderer, so there’s no need for you to create those components.
Similar to JSON Schema types, each Lightning type has its own type-specific keywords that apply only to that type.
You can use these standard Lightning types. However, support for specific types varies by application.
- `lightning__booleanType`
- `lightning__dateType`
- `lightning__dateTimeType`
- `lightning__dateTimeStringType`
- `lightning__integerType`
- `lightning__multilineTextType`
- `lightning__numberType`
- `lightning__objectType`
- `lightning__richTextType`
- `lightning__textType`
- `lightning__timeType`
- `lightning__urlType`
For information about the keywords available and the default editor and renderer associated with each of the Lightning types, see [Lightning Types Reference](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-references.md#lightning-types).
## Custom Lightning Types
Create custom Lightning types to customize the appearance of the UI. With custom Lightning types, you override the default user interface to manage complex interactions within Salesforce.
To create custom lightning types in Salesforce, use the LightningTypeBundle metadata component. For information about how to create custom Lightning types, see [LightningTypeBundle Metadata API](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-core.md#lightningtypebundle-metadata-type).
Benefits:
- **Enhanced UI Customization**
Standard Lightning types have predefined UI components. However, they don’t always fit your design needs or the user experience. Custom Lightning types give you full control over the UI. You can create tailored components that match your specific styling and behavior requirements. This customization ensures that the interface looks and functions exactly as you need for your application.
- **Handling Complex Data Structures**
Standard Lightning types sometimes can’t handle complex data, but custom Lightning types can manage and render complex data structures. For example, they can handle deeply nested objects, complex arrays, and dynamic fields that change based on user input. With custom Lightning types, you can build UIs that display complex data smoothly. Customize your UI to handle complex data structures, and you ensure that your Salesforce actions can accommodate even the most detailed and dynamic workflows.
## Categories of Custom Lightning Types
Custom Lightning types fall into two categories based on how you define their schema.
- [**Apex-based custom Lightning types**](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-apex.md). Use these types when you define the schema by referencing an Apex class. This method is for when you have a complex data structure already defined in an Apex class code. These types can be used for Agentforce Employee agents in Lightning Experience, Agentforce Service agents through [Enhanced Chat v2](https://help.salesforce.com/s/articleView?id=service.enhanced_chat_v2_intro.htm&type=5), Agentforce Employee agents on Mobile, and Agentforce Service agents via Enhanced Chat v2 on Mobile.
- [**Object-based custom Lightning types**](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-object.md). Use these types when you define a custom schema by specifying its properties directly. This method is for defining a custom JSON object structure without referencing an Apex class. These types can be used in Experience Builder and Prompt Builder.
# Lightning Type UI Configuration
The UI configuration files in a [LightningTypeBundle](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-core.md#understand-the-lightningtypebundle-structure) control the visual representation of your custom Lightning type. By organizing these files into channel-specific folders, you can define unique UI experiences.
## Channels
The channel identifies the Salesforce application that displays your custom Lightning type. A channel subfolder stores the Saleforce app’s configuration files.
This table lists the supported configuration files and override capabilities for each channel.
| Channel | Editor Support | Renderer Support | Top-Level Override | Property-Level Override |
| ----------------------- | -------------- | ---------------- | ------------------ | ----------------------- |
| `lightningDesktopGenAi` | Yes | Yes | Yes | No |
| `lightningMobileGenAi` | Yes | Yes | Yes | No |
| `experienceBuilder` | Yes | No | Yes | Yes |
| `enhancedWebChat` | Yes | Yes | Yes | No |
If `enhancedWebChat` isn’t configured, it uses the configuration defined in `lightningDesktopGenAi`.
## Customizing Lightning Type UI: LWCs vs. Widgets
You can customize the UI for custom Lightning types by using two approaches:
**Lightning Web Components (LWC)**
- Code-based customization (`JavaScript`, `HTML`, `CSS`)
- Supports both input (`editor.json`) and output (`renderer.json`)
- Channel-specific configurations in subfolders (`lightningDesktopGenAi/`, `experienceBuilder/`)
- Available for Salesforce applications only
**HXL Widgets (Beta)**
- JSON-based declarative composition
- Output (`renderer.json`) only
- Root-level `renderer.json` without channel subfolders
- Works across Salesforce applications and across third-party platforms, such as ChatGPT, Claude, and Slackbot, through Model Context Protocol
For widget configuration details, see [Build Rich UI Experiences with HXL Widgets](https://developer.salesforce.com/docs/platform/hxl/guide/hxl-rich-ui.html).
## UI Configuration Files
To configure the UI behavior, add these JSON files to the channel folder.
### Customize How User Input Is Collected
Modify the `editor.json` file to specify which input Lightning web component and layouts to use.
This example configures the custom Lightning type `flightFilter`.
```
+--lightningTypes
+--flightFilter
+--schema.json
+--lightningDesktopGenAi <-- Channel-specific folder
+--editor.json
```
### Customize How Data Is Present to Users
Modify the `renderer.json` file to specify which output Lightning web component to use to render the type or its individual properties. The renderer is used wherever the type appears as output within the channel.
This example configures the renderer for the custom Lightning type `flightFilter`.
```
+--lightningTypes
+--flightFilter
+--schema.json
+--lightningDesktopGenAi <-- Channel-specific folder
+--renderer.json
```
**See Also**
- [Lightning Types Configuration Files](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-core.md#lightning-types-configuration-files)
- [Understand the LightningTypeBundle Structure](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-core.md#understand-the-lightningtypebundle-structure)
- [Configuring Component Overrides](#configuring-a-component-override)
## Lightning Web Component Attribute Mapping
Attribute mapping creates a bridge between your data model and your interface. To display or edit data by using a custom Lightning web component (LWC), you map the properties defined in your `schema.json` to the component’s properties.
When mapping, these elements are required.
- **Source**: The data properties defined in your `schema.json`.
- **Connector**: The `attributes` object in your configuration file (editor.json or renderer.json), which uses the `{!$attrs.propertyName}` syntax.
- **Destination**: The properties in your LWC, decorated with `@api`.
In the `editor.json` and `renderer.json` files, use the `attributes` key in the `componentOverrides` section to map the properties.
- **Key**: The name of the property in your LWC (the variable with `@api`).
- **Value**: The schema reference that uses the syntax `{!$attrs.propertyName}`.
This sample code references `myExistingFilterComponent` to override the editor for the `Filter` input in the `editor.json` file.
```json
{
"editor": {
"componentOverrides": {
"$": {
"definition": "c/myExistingFilterComponent",
"attributes": {
"cost": "{!$attrs.price}",
"discountPercentage": "{!$attrs.discountPercentage}"
}
}
}
}
}
```
## Layout Configuration
Use the `layout` section in `editor.json` to control the visual arrangement and hierarchy of schema properties within the editor.
By default, the UI renders properties in a simple vertical stack that matches the order defined in your `schema.json` file. Define a custom layout section to achieve complex arrangements, such as:
- **Grouping**: Place properties side-by-side by using a horizontal layout.
- **Organization**: Group properties into structured containers, such as tabs or accordions.
- **Reordering**: Display properties in a sequence different from the schema definition.
This sample code shows how to arrange properties horizontally and apply a component override in the `editor.json` file.
```json
{
"editor": {
"componentOverrides": {
"lastName": {
"definition": "c/customLastNameInput"
}
},
"layout": {
"definition": "lightning/verticalLayout",
"children": [
{
"definition": "lightning/horizontalLayout",
"children": [
{
"definition": "lightning/propertyLayout",
"attributes": { "property": "firstName" }
},
{
// This will render the overridden c/customLastNameInput
// defined in componentOverrides above.
"definition": "lightning/propertyLayout",
"attributes": { "property": "lastName" }
}
]
}
]
}
}
}
```
## Component Override
The `componentOverrides` section in your JSON files controls which components render the data. You can override the UI for the entire type or for specific fields within it.
**Top-Level Override**
To use a single LWC to render the entire Lightning type, use the `$` symbol as the key. In this configuration, the component receives the full schema payload and is responsible for rendering all properties together, for example, as a summary card or composite UI.
This example references `myFilterComponent` to override the editor for the `Filter` input in the `editor.json` file.
```json
{
"editor": {
"componentOverrides": {
"$": {
"definition": "c/myFilterComponent"
}
}
}
}
```
**Property-Level Override**
To use a specific LWC to render an individual property within the type, use the property name (such as lastName) as the key in the `componentOverrides` section. In this configuration, the component renders only the specified property, and default editors handle the rest of the type.
This example references `customLastNameInput` to override the editor for the `lastName` property in the `editor.json` file.
```json
{
"editor": {
"componentOverrides": {
"lastName": {
"definition": "c/customLastNameInput"
}
}
}
}
```
## Configuring a Component Override
Use these examples to configure UI overrides for your custom Lightning types. For details on each configuration, see these topics.
- [Define a Top-Level Editor Override](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-custom-editor.md)
- [Define a Top-Level Renderer Override](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-custom-renderer.md)
- [Define a Top-Level Collection Renderer Override](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-custom-collection-renderer.md)
- [Define a Property-Level Editor Override](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-custom-editor-property.md)
## Preview Custom UI for Lightning Types in Your IDE Using Live Preview
To quickly iterate on the look and feel of custom editors and renderers built with Lightning web components, use the Salesforce Live Preview extension for Visual Studio Code (VS Code). Live Preview shows real-time component changes in a dedicated panel in VS Code. The preview refreshes automatically when you save local changes, so you can test component design and behavior without leaving your workspace.
You can find more details about this extension in [Visual Studio Code Marketplace: Salesforce Live Preview](https://marketplace.visualstudio.com/items?itemName=salesforce.salesforcedx-vscode-ui-preview).
**tip:** Consider using Lightning Preview in tandem with [Agentforce Vibes](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/einstein-overview.html), an AI assistant that can help you write, refactor, and test your code. For fast and easy iteration on your components, Agentforce Vibes can directly open components in the Lightning Preview panel when your local changes are complete.
Before you use Live Preview, complete the setup instructions in [Set Up Live Preview](https://developer.salesforce.com/docs/platform/lwc/guide/get-started-test-components.html#set-up-live-preview). To open a component in the Lightning Preview panel, use one of these three methods.
**IDE Context Menu**
1. In the VS Code Explorer, go to your Lightning Type bundle.
2. Right-click the `editor.json` file (for input UI) or the `renderer.json` file (for output UI).
3. Select **SFDX: Open in Lightning Preview**.
The preview opens in a dedicated panel or browser tab. As you save changes to the associated LWC’s HTML or CSS files, the preview updates automatically.
**IDE Command Palette**
Open the Command Palette in VS Code, search for `SFDX: Open in Lightning Preview`, and then select **SFDX: Open in Lightning Preview**. When prompted, enter or select the name of the component you want to preview.
**Agent Integration**
If you’re using Agentforce Vibes, you can instruct the agent to preview a component after it’s finished updating your code. The agent automatically opens the component in the Lightning Preview panel.
**See Also**
- [_Lightning Web Components Developer Guide_: Run a Live Component Preview](https://developer.salesforce.com/docs/platform/lwc/guide/get-started-test-components.html)
- [Visual Studio Code Marketplace: Salesforce Live Preview](https://marketplace.visualstudio.com/items?itemName=salesforce.salesforcedx-vscode-ui-preview)
# Lightning Types Glossary
This page redirects to [reference page](/docs/platform/lightning-types/references/lightning-types/lightning-types-glossary.html).
# Lightning Types Glossary of Terms
Learn more about the terms used in Lightning Types at Salesforce.
## Apex Class
A template or blueprint for creating Apex objects. Use an Apex class to define the data structure (schema) for Custom Lightning Types.
## Channel
A specific context or connection, such as `lightningDesktopGenAi` for the Agentforce panel, where you can override a custom Lightning type’s connections and the default UI. Different channels can have different `editor.json` and `renderer.json` configurations within the Lightning Type Bundle.
## Collection Renderer
A specific type of renderer defined within `renderer.json` that uses the collection keyword to customize the display of a structured list or array of data.
## Custom Lightning Type
A developer-created, JSON-based data type used to define a custom structure, validation, and user interface (UI) for complex data in Agentforce and other Salesforce applications.
## Editor
The part of a Lightning Type that defines input UI components used to enter or edit data. In a Custom Lightning Type bundle, this configuration resides in `editor.json`.
## Fully Qualified Name (FQN)
A unique name that identifies a metadata component, often by combining a namespace with the component’s developer name. For example, the `lightning:type` keyword in `schema.json` uses an FQN to reference an Apex class, such as `@apexClassType/c__AvailableFlight`.
## JSON Schema
A standard specification used to define the structure, constraints, and validation rules for JSON data. The `schema.json` file in a Lightning Type Bundle uses this specification.
## Keyword
A reserved term in a `schema.json` file that defines a specific aspect of the data’s structure or validation rules. For example, `title`, `properties`, and `lightning:type` are keywords.
## Lightning Type
A JSON Schema-based data type used to structure, validate, and display data, consisting of a schema, an optional editor, and an optional renderer. Lightning Types include Standard Lightning Types and Custom Lightning Types.
See [Standard Lightning Types](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types.html#standard-lightning-types) and [Custom Lightning Types](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types.html#custom-lightning-types).
## Lightning Type Bundle
The metadata component, with the API name LightningTypeBundle, used to create and deploy Custom Lightning Types. It’s stored in the lightningTypes folder and contains the `schema.json` file and, optionally, channel-specific folders with `editor.json` and `renderer.json` files.
## Lightning Web Component (LWC)
A UI framework built on standard HTML, JavaScript, and CSS for creating custom user interface components on the Salesforce platform. Use LWCs to define the custom Editor and Renderer for Custom Lightning Types.
## Metadata API
A Salesforce API used for retrieving, deploying, creating, updating, or deleting customization information, such as Custom Lightning Type Bundles.
## Namespace
A unique identifier used to distinguish metadata components. Use the default `c` namespace for components created in your org, or use the package’s namespace—for example, `isv`—for components from a managed package.
## Renderer
The part of a Lightning Type that defines the output UI component used to display data. In a Custom Lightning Type bundle, this configuration resides in `renderer.json`.
## Schema
The part of a Lightning Type that defines the data’s structure and validation rules by using the JSON Schema specification. In a Custom Lightning Type bundle, this configuration resides in `schema.json`.
## Standard Lightning Type
An out-of-the-box Lightning Type provided by Salesforce that includes a default schema, editor, and renderer. For example, lightning\_\_textType and lightning\_\_booleanType are standard Lightning types.
# Lightning Types Reference
This page redirects to [reference page](/docs/platform/lightning-types/references/lightning-types/lightning-types-reference.html).
# Lightning Types Reference
This section describes the keywords available and the default editor and renderer associated with each of the Lightning types.
**note:** The default editor and renderer examples in this section display the default interface for the Agentforce Employee agent in Lightning Experience. Component rendering varies by deployment target. For mobile interfaces, see [Considerations for Agentforce in the Salesforce Mobile App](https://help.salesforce.com/s/articleView?id=xcloud.salesforce_app_einstein_considerations.htm&type=5).
## lightning\_\_booleanType
The `lightning__booleanType` Lightning type corresponds to the boolean type in a JSON schema. It produces only two values, true or false.
**For Use In**
Agentforce Employee agent in Lightning Experience, Agentforce Service agent via Enhanced Chat v2, Agentforce Employee agent on Mobile, Agentforce Service agent via Enhanced Chat v2 on Mobile, Prompt Builder, and Experience Builder
| lightning\_\_booleanType | |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Editor Description | When the type receives user input, it appears as a toggle in the UI.
Default editor example:
![A toggle switch indicating that a Boolean property is active.](https://developer.salesforce.com/docs/platform/media/lightning-types-images/Boolean-1-Updated.png '{"class": "image-xs image-framed"}') |
| Renderer Description | When the type produces output, it’s rendered as a `true` or `false` value.
Default Renderer example:
![Text displaying the boolean value 'true'.](https://developer.salesforce.com/docs/platform/media/lightning-types-images/Boolean-2.png '{"class": "image-xs image-framed"}') |
For information about boolean type, see [Understanding JSON Schema: boolean](https://json-schema.org/understanding-json-schema/reference/boolean).
The `lightning__booleanType` Lightning type supports these configurable keywords.
| Keyword | Required | Type | Description |
| ------------- | -------- | ------ | ------------------------------------------------- |
| `title` | Yes | String | The label text for the toggle |
| `description` | No | String | The help text that describes the toggle’s purpose |
## lightning\_\_dateType
The `lightning__dateType` Lightning type uses a string type to specify the date data in the format `yyyy-mm-dd`.
**For Use In**
Agentforce Employee agent in Lightning Experience, Agentforce Service agent via Enhanced Chat v2, Agentforce Employee agent on Mobile, Agentforce Service agent via Enhanced Chat v2 on Mobile, Prompt Builder, and Experience Builder
| lightning\_\_dateType | |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Editor Description | When the type receives user input, it appears as a date picker in the UI.
Default editor example:
![A date picker set to February 21, 2025.](https://developer.salesforce.com/docs/platform/media/lightning-types-images/Date-1.png '{"class": "image-xs image-framed"}') |
| Renderer Description | When the type produces output, it’s rendered as a `date` data.
Default Renderer example:
![The date December 25, 2025.](https://developer.salesforce.com/docs/platform/media/lightning-types-images/Date-2.png '{"class": "image-xs image-framed"}') |
The `lightning__dateType` Lightning type supports these configurable keywords.
| Keyword | Required | Type | Description |
| ------------- | -------- | ------ | ------------------------------------------------------------- |
| `title` | Yes | String | The label text for the date field |
| `description` | No | String | The help text that explains the purpose of the date selection |
## lightning\_\_dateTimeType
The `lightning__dateTimeType` Lightning type describes the complex Lightning type `lightning__objectType`, which contains the `dateTime` and `timeZone` (optional) properties. Use the `lightning__dateTimeType` Lightning type to specify date and time together.
Because `lightning__dateTimeType` is a standard complex Lightning type, the value of the type is represented as an object.
This table shows the properties of the object type that the `lightning__dateTimeType` Lightning type describes.
| Property | Required or Optional | Type | Description |
| -------- | -------------------- | ------ | -------------------------------------------------------------------- |
| dateTime | Required | String | Specify the date value in `yyyy-MM-dd'T'HH:mm:ss.SSSZ` format. |
| timeZone | Optional | String | Specify the time zone information in IANA time zone database format. |
This example shows an object with valid date and time values.
```
{
"dateTime": "2012-05-31T01:30:05.000Z",
"timeZone": "Asia/Kolkata"
}
```
**For Use In**
Experience Builder, Agentforce Employee agent on Mobile, and Agentforce Service agent via Enhanced Chat v2 on Mobile
| lightning\_\_dateTimeType | |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Editor Description | When the type receives user input, it appears as a date picker and a time picker in the UI.
Default editor example:
![A form that displays a date, time, and time zone.](https://developer.salesforce.com/docs/platform/media/lightning-types-images/Date-Time-1.png '{"class": "image-xs image-framed"}') |
| Renderer Description | When the type produces output, it’s rendered as a `date` and `time` data.
Default Renderer example:
![A timestamp indicating April 11, 2024, at 8:36 PM.](https://developer.salesforce.com/docs/platform/media/lightning-types-images/Date-Time-2.png '{"class": "image-xs image-framed"}') |
The `lightning__dateTimeType` Lightning type supports these configurable keywords.
| Keyword | Required | Type | Description |
| ------------- | -------- | ------ | ------------------------------------------------------------------------------- |
| `title` | Yes | String | The label text for the datetime field |
| `description` | No | String | The help text that provides context for selecting the date, time, and time zone |
## lightning\_\_dateTimeStringType
The `lightning__dateTimeStringType` Lightning type describes date, time, and time zone in standard ISO 8601 format. Use the `lightning__dateTimeStringType` Lightning type to specify date and time together in a standard ISO 8601 format string.
**For Use In**
Agentforce Employee agent in Lightning Experience, Agentforce Service agent via Enhanced Chat v2, Agentforce Employee agent on Mobile, Agentforce Service agent via Enhanced Chat v2 on Mobile, and Prompt Builder
| lightning\_\_dateTimeStringType | |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Editor Description | When the type receives user input, it appears as a date and time picker in the UI.
Default editor example:
![A form with separate input fields for Date and Time.](https://developer.salesforce.com/docs/platform/media/lightning-types-images/Date-Time-String-1.png '{"class": "image-xs image-framed"}') |
| Renderer Description | When the type produces output, it’s rendered as a `date` and `time` data. |
The `lightning__dateTimeStringType` Lightning type supports these configurable keywords.
| Keyword | Required | Type | Description |
| ------------- | -------- | ------ | ------------------------------------------------------------------------------- |
| `title` | Yes | String | The label text for the datetime field |
| `description` | No | String | The help text that provides context for selecting the date, time, and time zone |
## lightning\_\_integerType
Use the `lightning__integerType` Lightning type to specify integers. The type applies to whole numbers. The `lightning__integerType` Lightning type corresponds to the integer type in a JSON schema.
**For Use In**
Agentforce Employee agent in Lightning Experience, Agentforce Service agent via Enhanced Chat v2, Agentforce Employee agent on Mobile, Agentforce Service agent via Enhanced Chat v2 on Mobile, Prompt Builder, and Experience Builder
| lightning\_\_intergerType | |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Editor Description | When the type receives user input, it appears as a numeric input field in the UI.
Default editor example:
![An integer field with the value 5 entered.](https://developer.salesforce.com/docs/platform/media/lightning-types-images/Integer-1.png '{"class": "image-xs image-framed"}') |
| Renderer Description | When the type produces output, it’s rendered as a number display field.
Default Renderer example:
![A text box displaying an integer value of 5.](https://developer.salesforce.com/docs/platform/media/lightning-types-images/Integer-2.png '{"class": "image-xs image-framed"}') |
For information about the integer type in JSON Schema, see [Understanding JSON Schema: integer](https://json-schema.org/understanding-json-schema/reference/numeric).
The `lightning__integerType` Lightning type supports these configurable keywords.
| Keyword | Required | Type | Description |
| ------------- | -------- | ------ | ------------------------------------------------------------------------------------------- |
| `maximum` | No | Number | The maximum allowed integer value. Input can’t exceed this value. |
| `minimum` | No | Number | The minimum allowed integer value. Input lower than this value triggers a validation error. |
| `title` | Yes | String | The label text for the input field |
| `description` | No | String | The help text that describes the expected input |
## lightning\_\_multilineTextType
The `lightning__multilineTextType` Lightning type is similar to `lightning__textType`, but it accommodates a larger maximum character length and an editor for larger text input. The `lightning__multilineTextType` Lightning type corresponds to the string type in a JSON schema.
**For Use In**
Agentforce Employee agent in Lightning Experience, Agentforce Service agent via Enhanced Chat v2, Prompt Builder, and Experience Builder
| lightning\_\_multilineTextType | |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Editor Description | When the type receives user input, it appears as a multiline text input field on the UI.
Default editor example:
![A multiline text field with sample text entered.](https://developer.salesforce.com/docs/platform/media/lightning-types-images/MultiLineText-1.png '{"class": "image-xs image-framed"}') |
| Renderer Description | When the type produces output, it’s rendered as a multiline text display field. |
For information about string types in JSON Schema, see [Understanding JSON Schema: string](https://json-schema.org/understanding-json-schema/reference/string).
The `lightning__multilineTextType` Lightning type supports these configurable keywords.
| Keyword | Required | Type | Description |
| ------------- | -------- | ------ | ----------------------------------------------------------------------------------------------------- |
| `maxLength` | No | Number | The maximum number of characters allowed. Input can’t exceed this limit. |
| `minLength` | No | Number | The minimum number of characters required. Input shorter than this limit triggers a validation error. |
| `title` | Yes | String | The label text for the text area |
| `description` | No | String | The help text that provides instructions for the input |
## lightning\_\_numberType
Use the `lightning__numberType` Lightning type to specify numbers. This type is validated as a decimal number, also known as a float in some programming languages. The `lightning__numberType` Lightning type corresponds to the number type in a JSON schema.
**For Use In**
Agentforce Employee agent in Lightning Experience, Agentforce Service agent via Enhanced Chat v2, Agentforce Employee agent on Mobile, Agentforce Service agent via Enhanced Chat v2 on Mobile, Prompt Builder, and Experience Builder
| lightning\_\_numberType | |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Editor Description | When the type receives user input, it appears as a decimal number input field in the UI.
Default editor example:
![A decimal number field with the value 1.32 entered.](https://developer.salesforce.com/docs/platform/media/lightning-types-images/Number-1.png '{"class": "image-xs image-framed"}') |
| Renderer Description | When the type produces output, it’s rendered as a decimal number display field.
Default Renderer example:
![A text box displaying a decimal number value of 15.15.](https://developer.salesforce.com/docs/platform/media/lightning-types-images/Number-2.png '{"class": "image-xs image-framed"}') |
For information about number type in JSON Schema, see [Understanding JSON Schema: number](https://json-schema.org/understanding-json-schema/reference/numeric).
The `lightning__numberType` Lightning type supports these configurable keywords.
| Keyword | Required | Type | Description |
| ------------- | -------- | ------ | ------------------------------------------------------------------------------------------------- |
| `maximum` | No | Number | The maximum allowed numeric value. Input can’t exceed this value. |
| `minimum` | No | Number | The minimum allowed numeric value. Input lower than this value triggers a validation error. |
| `multipleOf` | No | Number | The step value for increasing or decreasing the number. If not specified, the default is 1.0E-32. |
| `title` | Yes | String | The label text for the input field |
| `description` | No | String | The help text that describes the expected input, such as the unit of measurement |
## lightning\_\_objectType
Use the `lightning__objectType` lightning type to create object lightning types. This complex Lightning type can contain sub-properties, each with its own Lightning type.
With `lightning__objectType`, you can group other lightning types. The `lightning__objectType` lightning type corresponds to the object type defined in a JSON schema.
For information about object types in JSON Schema, see [Understanding JSON Schema: object](https://json-schema.org/understanding-json-schema/reference/object).
**For Use In**
Agentforce Employee agent in Lightning Experience, Agentforce Service agent via Enhanced Chat v2, Agentforce Employee agent on Mobile, Agentforce Service agent via Enhanced Chat v2 on Mobile, Prompt Builder, and Experience Builder
## lightning\_\_richTextType
Use the `lightning__richTextType` Lightning type to add, edit, and delete rich text data. You can enter input text data of up to 100,000 characters.
**For Use In**
Agentforce Employee agent in Lightning Experience, Agentforce Service agent via Enhanced Chat v2, Agentforce Employee agent on Mobile, Agentforce Service agent via Enhanced Chat v2 on Mobile, Prompt Builder, and Experience Builder
| lightning\_\_richTextType | |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Editor Description | When the type receives user input, it appears as a rich text input field in the UI.
Default editor example:
![A rich text editor with formatting options and a sample text box.](https://developer.salesforce.com/docs/platform/media/lightning-types-images/RichText-1.png '{"class": "image-xs image-framed"}') |
| Renderer Description | When the type produces output, it’s rendered as a rich text display field. |
For information about rich text editor, see [Rich Text Editor](https://help.salesforce.com/s/articleView?id=platform.fields_using_html_editor.htm&type=5).
The `lightning__richTextType` Lightning type supports these configurable keywords.
| Keyword | Required | Type | Description |
| ------------- | -------- | ------ | ----------------------------------------------------------------- |
| `maxLength` | No | Number | The maximum number of characters allowed |
| `minLength` | No | Number | The minimum number of characters required (including HTML markup) |
| `title` | Yes | String | The label text for the rich text editor |
| `description` | No | String | The help text that describes the expected content or formatting |
## lightning\_\_textType
Use the `lightning__textType` Lightning type for text fields, such as titles and descriptions. You can enter input text data of up to 255 characters. The `lightning__textType` Lightning type corresponds to the string type in a JSON schema.
**For Use In**
Agentforce Employee agent in Lightning Experience, Agentforce Service agent via Enhanced Chat v2, Agentforce Employee agent on Mobile, Agentforce Service agent via Enhanced Chat v2 on Mobile, Prompt Builder, and Experience Builder
| lightning\_\_textType | |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Editor Description | When the type receives user input, it appears as a text input field on the UI.
Default editor example:
![A text field with sample text entered.](https://developer.salesforce.com/docs/platform/media/lightning-types-images/Text-1.png '{"class": "image-xs image-framed"}') |
| Renderer Description | When the type produces output, it’s rendered as a text display field.
Default Renderer example:
![A text box displaying sample text.](https://developer.salesforce.com/docs/platform/media/lightning-types-images/Text-2.png '{"class": "image-xs image-framed"}') |
The `lightning__textType` Lightning type supports these configurable keywords.
| Keyword | Required | Type | Description |
| ------------- | -------- | ------ | ----------------------------------------------- |
| `maxLength` | No | Number | The maximum number of characters allowed |
| `minLength` | No | Number | The minimum number of characters required |
| `title` | Yes | String | The label text for the text field |
| `description` | No | String | The help text that describes the expected input |
## lightning\_\_timeType
Use the `lightning__timeType` Lightning type for time-specific fields, such as appointment time or arrival time. You can input time using the format `HH:MM:SS.000Z` (UTC) or `HH:MM:SS`. The format includes hours, minutes, seconds, and optional milliseconds.
**For Use In**
Agentforce Employee agent in Lightning Experience, Agentforce Service agent via Enhanced Chat v2, Agentforce Employee agent on Mobile, Agentforce Service agent via Enhanced Chat v2 on Mobile, and Prompt Builder
| lightning\_\_timeType | |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Editor Description | When the type receives user input, it appears as a time picker in the UI.
Default editor example:
![A time input field labeled 'Enter time' populated with the value 23:58:27@586.](https://developer.salesforce.com/docs/platform/media/lightning-types-images/Time-1.png '{"class": "image-xs image-framed"}') |
| Renderer Description | When the type produces output, it’s rendered as a time string displayed.
Default Renderer example:
![The text value 21:11:28~185Z displayed on screen.](https://developer.salesforce.com/docs/platform/media/lightning-types-images/Time-2.png '{"class": "image-xs image-framed"}') |
The `lightning__timeType` Lightning type supports these configurable keywords.
| Keyword | Required | Type | Description |
| ------------- | -------- | ------ | ------------------------------------------------------------- |
| `title` | Yes | String | The label text for the time field |
| `description` | No | String | The help text that explains the purpose of the time selection |
## lightning\_\_urlType
Use the `lightning__urlType` Lightning type for URL values. To specify the url schemes that the type can validate against, configure `lightning:allowedUrlSchemes` parameter of the Lightning type.
**For Use In**
Agentforce Employee agent in Lightning Experience, Agentforce Service agent via Enhanced Chat v2, Prompt Builder, and Experience Builder
| lightning\_\_urlType | |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Editor Description | When the type receives user input, it appears as a URL input field in the UI.
Default editor example:
![A field with a sample URL entered.](https://developer.salesforce.com/docs/platform/media/lightning-types-images/URL-1.png '{"class": "image-xs image-framed"}') |
| Renderer Description | When the type produces output, it’s rendered as a hyperlink. |
The `lightning__urlType` Lightning type supports these configurable keywords.
| Keyword | Required | Type | Description |
| ----------------------------- | -------- | -------- | ----------------------------------------------------------------------- |
| `lightning:allowedUrlSchemes` | No | String[] | An array of supported URL schemes, such as `https`, `http`, or `mailto` |
| `title` | Yes | String | The label text for the URL field |
| `description` | No | String | The help text that describes the expected URL format |
# Object-Based Custom Lightning Types
With object-based custom Lightning types, you can define a custom data structure entirely within a JSON schema, without relying on an Apex class. You explicitly define every property, data type, and validation rule in the `schema.json` file. Use this approach when you need a lightweight, flexible data model for UI configuration or prompt definitions that don’t require an Apex backend.
**Supported in**:
- Prompt Builder
- Experience Builder
## Schema.json for Object-Based Custom Lightning Types
For object-based types, you define the data structure directly in the `schema.json` file by using the `lightning__objectType` value and a `properties` block.
This table lists the keywords that you can specify in a `schema.json` file.
| Keyword | Required or Optional | Type | Description |
| ---------------- | -------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title` | Required | String | Name for the Lightning type |
| `description` | Optional | String | Description for the Lightning type |
| `lightning:type` | Required | String | Refers to lightning\_\_objectType type by fully qualified name |
| `properties` | Required | Object | Defines the fields for the object. Each key is a field name, and its value is an object defining that field’s `title` and `lightning:type`.
For a list of valid values, see [Lightning Types Reference](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-references.md#lightning-types). |
| `required` | Optional | Array | An array of property names that must be present in the data |
Here’s a sample code that shows the contents of the `schema.json` file for a custom Lightning type `customerFeedback`.
```json
{
"title": "customerFeedback",
"description": "Structured format for capturing customer feedback received.",
"lightning:type": "lightning__objectType",
"properties": {
"customerName": {
"title": "customerName",
"lightning:type": "lightning__textType"
},
"feedbackDate": {
"title": "feedbackDate",
"lightning:type": "lightning__dateType"
},
"satisfactionScore": {
"title": "satisfactionScore",
"lightning:type": "lightning__numberType"
}
},
"required": ["customerName"]
}
```
**note:** When you create or update an object-based custom Lightning type, an Apex class is automatically generated that matches your schema.
**See Also**
- [Create Custom Labels for Custom Lightning Types](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-core.md#create-custom-labels-for-custom-lightning-types)
## UI Configuration for Object-Based Custom Lightning Types
While `schema.json` defines the data structure, the UI configuration files in the LightningTypeBundle control the visual representation. Organize these files by channel to support specific Salesforce applications.
[**Channels**](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.md#channels)
Store UI overrides in channel-specific subfolders to target different applications.
- **experienceBuilder**. Use this folder for Experience Builder sites.
[**Configuration Files**](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.md#ui-configuration-files)
Configure the UI override by using this JSON file.
- **editor.json**. Points to a Lightning Web Component (LWC) that serves as a custom form for data entry.
[**Component Override**](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.md#component-override)
You can customize the visual presentation by adding component overrides to your `editor.json` file.
- **Top-Level Override**. A top-level override replaces the default UI for the entire custom Lightning type. To configure this override, use the `$` symbol as the key in the `componentOverrides` section of your `editor.json`. This approach is useful for creating specialized interfaces, such as a custom card or a multi-property form handled by a single component.
- **Property-Level Override**. A property-level override replaces the default UI for specific properties of a schema within a complex type, while default editors handle the rest of the type. Instead of using `$`, specify the exact property name (such as address or phoneNumber) as the key in the `componentOverrides` section. Use property overrides when specific data requires specialized input. Default editors apply to any properties that don’t have a defined override.
[**Layout Configuration**](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.md#layout-configuration)
Defines the visual arrangement and hierarchy of schema properties. By default, the UI renders properties in a vertical stack matching the schema order. Use the `layout` section in `editor.json` to create complex arrangements, such as grouping properties horizontally or organizing them into tabs.
[**Attribute Mapping**](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.md#lightning-web-component-attribute-mapping)
In both configuration files, map schema properties to LWC component properties by using the `{!$attrs.PropertyName}` syntax.
**note:** For a complete list of supported channels and detailed JSON syntax, see [Lightning Type UI Configuration](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.md).
**LWC Target Requirements**
To use a component as an override, include the appropriate target in the component’s `js-meta.xml` file.
- [`lightning__PropertyEditor`](https://developer.salesforce.com/docs/platform/lwc/guide/targets-lightning-property-editor.html) for overrides
**See Also**
- [Lightning Types Configuration Files](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-core.md#lightning-types-configuration-files)
- [Lightning Type UI Configuration](https://developer.salesforce.com/docs/platform/lightning-types/guide/lightning-types-ui-config.md)
## Object-Based Custom Lightning Types Modification Guidelines
You can modify custom Lightning types freely until they’re referenced in a Salesforce application. When they’re referenced, follow these guidelines to maintain the integrity of the type across Salesforce applications, such as Experience Builder and Prompt Builder.
| Keyword | Status | Guideline |
| ----------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `title` | Permitted | You can change the title of an individual property. |
| `description` | Permitted | You can change the description of an individual property. |
| `lightning:type` | Prohibited | You can’t change the `lightning:type` value. |
| `properties` | Conditionally Permitted | **Additive changes**: You can add new optional properties.
**Destructive changes**: You can’t remove or rename an existing property. You can’t add a new required property. |
| `required` | Conditionally Permitted | You can make existing required properties optional (remove them from the required list).
You can’t add properties to the required list. |
| `maximum` | Conditionally Permitted | You can increase the value. You can’t decrease it. |
| `minimum` | Conditionally Permitted | You can decrease the value. You can’t increase it. |
| `maxLength` | Conditionally Permitted | You can increase the value. You can’t decrease it. |
| `minLength` | Conditionally Permitted | You can decrease the value. You can’t increase it. |
| `multipleOf` | Conditionally Permitted | The existing value must be divisible by the new value.
**Example**: If the existing value is 20, valid new values include 2, 4, 5, and 10. Invalid values include 15 and 40. |
| `lightning:allowedUrlSchemes` | Conditionally Permitted | You can add new schemes to the array. You can’t remove existing schemes. |
# Use Agentforce Vibes to Build Custom Lightning Types
Agentforce Vibes includes a built-in AI Skill to help you generate custom Lightning type metadata bundles faster. When you enter a prompt, Agentforce Vibes uses this skill to draft your `schema.json` file. If you need to customize the default UI configuration, it can also draft `editor.json` and `renderer.json` files for your Lightning web components.
For full details on the specific instructions and capabilities of this skill, see the `platform-custom-lightning-type-generate` skill in the [Skills Library on GitHub](https://github.com/forcedotcom/sf-skills/tree/main/skills/platform-custom-lightning-type-generate).
## Supported Capabilities for the Lightning Types Skill
When you work with custom Lightning types, you can:
- **Generate full bundles**: Create custom Lightning types from natural language descriptions and output the complete bundle (`schema.json`, `editor.json`, and `renderer.json`).
- **Modify local files**: Update existing custom Lightning types in your local VS Code workspace.
- **Iterate in real-time**: Apply continuous, iterative updates to custom Lightning types created within your current active session.
- **Incorporate retrieved metadata**: Update custom Lightning types by using metadata you have manually retrieved and provided to the prompt (for example, via Salesforce CLI or Metadata API).
## Considerations for the Lightning Types Skill
This skill works with metadata you provide or files in your local workspace. It doesn’t scan your org automatically.
- **Provide exact type names**: The skill can’t identify custom Lightning types from descriptions such as 'the booking type.' Use the exact API name.
- **No org-wide discovery**: The skill can’t detect similar custom Lightning types or recommend them for reuse before you create them.
- **No bulk updates**: You can’t perform bulk updates across multiple custom Lightning types simultaneously.
- **No dependency mapping**: The skill can’t identify or update custom Lightning types based on reference or dependency relationships in your org.
## Sample Prompts
Before you begin, install the [Salesforce Extension Pack](https://marketplace.visualstudio.com/items?itemName=salesforce.salesforcedx-vscode) for Visual Studio Code (VS Code). Then open the Agentforce Vibes panel and enter natural language prompts to generate your bundle. For best results, start with an action verb and clearly describe the properties you need.
Examples:
- “Create a custom Lightning type for a hotel booking system.”
- “Create a custom Lightning type based on the Apex class `com.example.model.HotelModel`.”
- “Create a custom Lightning type to store user preferences by using the appropriate skill.”
Based on your prompt, Agentforce Vibes automatically loads the relevant Lightning Types skill to guide metadata and code generation. To verify which skills are active, click the **Skills** icon (⚖️) at the bottom of the Agentforce Vibes panel.
**See Also**
- [_Agentforce Vibes Developer Guide_: Set Up Agentforce Vibes Extension](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/einstein-setup.html)
- [Skills GitHub Repository](https://github.com/forcedotcom/afv-library)
- [_Agentforce Vibes Developer Guide_: Skills in Agentforce Vibes](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/skills.html)