CompactLayout Metadata Type Reference

The CompactLayout metadata type controls which key summary fields appear in the Lightning Experience Highlights Panel, lookup hover cards, Global Search preview panels, Outlook/Gmail sidebars, and the Salesforce Mobile app record header. Introduced in API version 29.0, a well-designed CompactLayout lets users scan a record’s identity, status, owner, and value at a glance without scrolling through tabs.

In Salesforce DX projects, compact layouts are decomposed inside their parent object folder at force-app/main/default/objects/<ObjectName>/compactLayouts/<LayoutName>.compactLayout-meta.xml.

Field Limits and Unsupported Field Types#

• Maximum Fields Defined: Up to 10 <fields> per CompactLayout.
• First Field Rule: Always place the object’s Name (or CaseNumber / Subject / ContractNumber) as the first <fields> entry, because Lightning Experience renders the first field in the large header font at the top-left of the Highlights Panel.
• Unsupported Field Types: You cannot include TextArea, LongTextArea, Html (Rich Text), or MultiselectPicklist fields in a CompactLayout.

Key Metadata Fields#

Production-Grade XML Example#

Below is a CompactLayout for Opportunity (force-app/main/default/objects/Opportunity/compactLayouts/Enterprise_Deal_Summary.compactLayout-meta.xml):

<?xml version="1.0" encoding="UTF-8"?>
<CompactLayout xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Enterprise_Deal_Summary</fullName>
    <fields>Name</fields>
    <fields>AccountId</fields>
    <fields>StageName</fields>
    <fields>Amount</fields>
    <fields>CloseDate</fields>
    <fields>OwnerId</fields>
    <fields>NextStep</fields>
    <label>Enterprise Deal Summary</label>
</CompactLayout>

Querying Compact Layouts via Tooling API#

You can inspect compact layouts and their assigned fields using the Tooling API:

-- 1. List Compact Layouts for a specific object (Tooling API)
SELECT Id, DeveloperName, MasterLabel, SobjectType, NamespacePrefix
FROM CompactLayout
WHERE SobjectType = 'Opportunity'

-- 2. Inspect CompactLayoutInfo via standard/Tooling SOQL
SELECT Id, DeveloperName, MasterLabel, EntityDefinition.QualifiedApiName
FROM CompactLayoutInfo
WHERE EntityDefinition.QualifiedApiName = 'Opportunity'

Retrieval and Deployment (package.xml)#

In package.xml, reference CompactLayout members using the <ObjectName>.<CompactLayoutName> syntax:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Opportunity.Enterprise_Deal_Summary</members>
        <name>CompactLayout</name>
    </types>
    <version>68.0</version>
</Package>

Frequently asked questions

How many fields can a CompactLayout display in the Lightning Experience Highlights Panel?

While you can add up to 10 fields to a CompactLayout definition, the desktop Lightning Experience Highlights Panel displays the first field as the main record title and up to 6 additional fields in the summary bar.

Which field types cannot be added to a CompactLayout?

Text Area, Long Text Area, Rich Text Area, and Multi-Select Picklist fields cannot be added to a CompactLayout.

Where are CompactLayout files stored in SFDX source format?

In SFDX source format, CompactLayout files are decomposed inside the parent object's folder at force-app/main/default/objects/ObjectName/compactLayouts/LayoutName.compactLayout-meta.xml.

How do I assign a CompactLayout as the primary default or per RecordType?

Set the compactLayoutAssignment field on the parent CustomObject metadata for the org-wide primary compact layout, and set the compactLayoutAssignment field inside each RecordType metadata file for record-type-specific overrides.

What happens if a user lacks Field-Level Security (FLS) for a field on a CompactLayout?

Salesforce automatically suppresses any field the running user lacks Read FLS permission for and shifts the remaining visible fields to the left without throwing an error.