Lightning Types
A Lightning Type is a Salesforce metadata feature that pairs a data type with the user interface used to enter and display that data.
Definition
A Lightning Type is a Salesforce metadata feature that pairs a data type with the user interface used to enter and display that data. Each type is built from a JSON schema that describes the shape and validation rules of the data, plus optional configuration that maps the type to a Lightning Web Component for input (an editor) and another for output (a renderer). The custom variety ships as a metadata bundle called LightningTypeBundle, available since API version 64.0.
The term is easy to confuse with the broader Lightning family of components and pages, but it means something specific. A Lightning Type answers one question: when a piece of data flows through Salesforce, what component should collect it and what component should show it? Salesforce uses these types to give richer interfaces to Agentforce agent actions, Experience Builder component properties, and flow Structured Outputs, instead of falling back to plain text fields.
How Lightning Types Map Data to Custom Interfaces
The three parts: schema, editor, renderer
Every Lightning Type is built from three artifacts, one required and two optional. The schema defines the data structure and its validation rules, such as maximum length, required fields, format, and type. It follows the JSON Schema specification, so it reads like a contract for what the data must look like. The editor defines the input component a user sees when entering or editing the data. The renderer defines the output component that displays the data once it exists. A date type is the classic teaching example. Its schema says the value is a date, its editor points at a date picker so users do not type free text, and its renderer formats the stored value for reading. You do not have to provide all three. A type with only a schema falls back to default Salesforce input and output for that data shape. You add an editor when the default form is clumsy, and you add a renderer when plain text does the data no justice. That separation is the whole idea. The data definition stays independent of how any one channel chooses to draw it on screen.
The LightningTypeBundle metadata bundle
Custom Lightning Types are packaged as a metadata type named LightningTypeBundle, introduced in API version 64.0. On disk the bundle lives under a lightningTypes folder. Inside that folder, each type gets its own subfolder named after the type. The type subfolder holds the required schema.json file. Channel-specific behavior sits one level deeper, in named channel folders such as lightningDesktopGenAi, lightningMobileGenAi, enhancedWebChat, and experienceBuilder. Each channel folder can carry an editor.json and a renderer.json that override the input and output for that surface. Because it is real metadata, a LightningTypeBundle deploys through Metadata API or Salesforce CLI, version-controls in source like any other component, and travels inside both 1GP and 2GP managed packages. The schema.json can reference custom labels with the {!$Label.c.LabelName} syntax, which keeps validation messages and titles translatable. One practical note worth remembering: the renderer override is not supported in the Experience Builder channel, so output customization there behaves differently from the Agentforce channels.
Why Agentforce needed them
The headline use case arrived with Agentforce. When an agent runs an action backed by an Apex class, the inputs and outputs are typed values, and by default the agent shows them as text in the conversation. That is fine for a name or a number, and poor for anything structured. Lightning Types let a developer attach a custom Lightning Web Component to those Apex inputs and outputs. A flight search action is the worked example Salesforce uses. Instead of a generic form, the input editor renders an accordion with price and discount sliders, which cuts the back and forth of clarifying questions. Instead of a wall of text, the output renderer draws each available flight as a card with a Book button, so the user acts straight from the agent reply. The schema describes the data the Apex action accepts and returns, the editor component handles collection, and the renderer component handles display. You assign the input or output deployment target to the LWC, then switch the action's display from default Apex to the custom type. The conversation gains a real interface without leaving the chat.
Custom property types for Experience Builder
Lightning Types also power custom property editors in Experience Builder, which is the other surface where authors configure components by hand. A component exposes properties, and each property has a type that drives the editor shown in the property panel. Salesforce ships standard types for common shapes, but some properties need a tailored control. Alignment pickers, border-style dropdowns, and color choosers are typical examples. When a standard type does not fit, you create a LightningTypeBundle, define the property shape in schema.json, and place an editor.json inside the experienceBuilder channel folder to map your custom property editor LWC. The component then references the type through the type and editor attributes in its js-meta.xml configuration file. The payoff is a property panel that feels designed rather than generic. Authors get sliders, dropdowns, and visual pickers instead of raw text boxes, and the validation defined in the schema keeps bad values out before they reach the page. Remember that renderer overrides do not apply here, so this surface is about better input, not custom output.
Standard types versus custom types
Not every Lightning Type is something you build. Salesforce provides a set of standard Lightning Types for everyday data shapes, and you reach both standard and custom types through the connect lightning-types REST resource. Standard types cover the basics so that simple properties and action arguments get a reasonable interface with no extra work. You only reach for a custom LightningTypeBundle when the standard set leaves a gap, which usually means the data is structured, the default control is awkward, or the output deserves a designed component rather than text. This mirrors a pattern that runs through the platform. Start with what Salesforce gives you, confirm it genuinely does not fit, then extend with metadata you own. Reviewing the Lightning Types Reference first is the recommended habit, because it is common to find a standard type that already covers the property or argument you were about to hand-build. Custom types are powerful, but each one is code and configuration you have to maintain across releases, so they earn their place rather than being the default choice.
Channels, packaging, and where it fits
A single Lightning Type can behave differently depending on where it appears, which is why channels exist. The same type might render one way in an Agentforce desktop conversation, another way in the mobile agent, and a third way inside Experience Builder, because each channel folder carries its own editor and renderer configuration. Today custom Lightning Types support the Agentforce Employee agent in Lightning Experience and mobile, the Agentforce Service agent through Enhanced Chat v2 on desktop and mobile, Experience Builder, Prompt Builder, and flows that use Structured Outputs. That spread is wider than it looks, because it touches both the agent surfaces and the older builder surfaces. Packaging is straightforward. Because the bundle is standard metadata, it deploys with the rest of your source and ships inside managed packages, so an ISV can distribute a custom type alongside the components that depend on it. The feature is still young, so check the release notes for the API version and channel support that match your org before you design around a specific behavior.
How to create a custom Lightning Type
Creating a custom Lightning Type means authoring a LightningTypeBundle and deploying it as metadata. You build the JSON files locally, map any custom editor or renderer Lightning Web Components, then deploy through Salesforce CLI or Metadata API. These are the core pieces every bundle needs.
- Create the bundle folder
Under your project's force-app metadata, add a lightningTypes folder, then a subfolder named after your type. This subfolder is the bundle for that one Lightning Type.
- Author schema.json
Write a schema.json that describes the data shape and its validation rules using JSON Schema. This file is required. Reference custom labels with {!$Label.c.LabelName} so titles and messages stay translatable.
- Add channel folders with editor and renderer
Inside the type folder, add channel folders such as experienceBuilder or lightningDesktopGenAi. Place an editor.json to map your input LWC and, where supported, a renderer.json to map your output LWC.
- Deploy and wire it up
Deploy the bundle with Salesforce CLI or Metadata API. Then reference the type from the consuming surface, such as the js-meta.xml of a component or the display setting of an Agentforce action.
The top-level container folder that holds every custom Lightning Type bundle in your project.
A folder named after the type. Its name is how components and actions reference the type.
Required. Defines the data structure and validation rules in JSON Schema. A bundle is not valid without it.
Optional. Maps a custom Lightning Web Component as the input editor for a given channel folder.
Optional. Maps a custom Lightning Web Component as the output renderer. Not supported in the Experience Builder channel.
- Renderer overrides do not work in the Experience Builder channel, so plan for custom input but default output there.
- LightningTypeBundle needs API version 64.0 or later. Confirm your org and project source API version support it.
- Check the Lightning Types Reference for a standard type before building a custom one. You may not need a bundle at all.
- Channel folder names are specific (for example lightningDesktopGenAi, enhancedWebChat). A typo means the override is silently ignored.
Prefer this walkthrough as its own page? How to Lightning Types in Salesforce, step by step
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Lightning Types.
Hands-on resources to go deeper on Lightning Types.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. Within the Lightning Types family, which item is the top-level container that defines the brand color, logo, navigation menu, and utility bar?
Q2. Among the Lightning Types, which one lets Lightning components run on external hosts like Visualforce, Heroku, or a custom website?
Q3. Which statement about the Lightning Types LWC and Aura correctly describes their relationship?
Discussion
Loading discussion…