FlexiPage Metadata Type and Dynamic Forms Guide

Overview#

The FlexiPage metadata type (flexipages/<PageName>.flexipage-meta.xml) represents a Lightning Page designed in Lightning App Builder or Experience Builder. A FlexiPage defines a layout template (flexipage:recordHomeTemplateDesktop), regions (flexiPageRegions), standard and custom LightningComponentBundle instances (componentInstances), Dynamic Forms field sections (fieldInstances), Dynamic Highlights Panels, and conditional component visibility filters (visibilityRule).

In modern Lightning Experience architecture, FlexiPage with Dynamic Forms and Dynamic Actions supersedes traditional Layout metadata for record pages: instead of creating dozens of page layouts and record types to show or hide fields based on record status, you use a single FlexiPage with declarative <visibilityRule> criteria on individual fields and sections.

As shown in the diagram above, a FlexiPage organizes componentInstances and Dynamic Forms fieldInstances inside flexiPageRegions with granular visibilityRule filters, while page activation is stored separately in CustomObject or CustomApplication metadata.

Prerequisites#

• Permissions: “Customize Application” and “View Setup and Configuration” permissions.
• Referenced Components: Every LWC (c:componentName), custom field, quick action, or custom permission referenced in a FlexiPage must exist in the target org or be deployed in the same transaction.
• API Version: Introduced in API version 29.0. Verified against API version 68.0 (Winter ’27).

Key FlexiPage XML Elements#

Querying FlexiPage via Tooling API#

The FlexiPage object is queryable via the Tooling API (sf data query --use-tooling-api).

1. List All Record Pages and Their Target Objects (Tooling API)#

SELECT Id, DeveloperName, MasterLabel, Type,
       EntityDefinition.QualifiedApiName, Description, LastModifiedDate, LastModifiedBy.Name
FROM FlexiPage
WHERE Type = 'RecordPage'
  AND ManageableState = 'unmanaged'
ORDER BY EntityDefinition.QualifiedApiName ASC, DeveloperName ASC

2. Audit Utility Bar and App Pages Across the Org (Tooling API)#

SELECT Id, DeveloperName, MasterLabel, Type, LastModifiedDate
FROM FlexiPage
WHERE Type IN ('AppPage', 'HomePage', 'UtilityBar')
ORDER BY Type ASC, DeveloperName ASC

Example#

The following Invoice_Record_Page.flexipage-meta.xml configures a Lightning RecordPage for Invoice__c with a Highlights Panel in the header and our custom c:invoiceSummary LWC in the main region, rendered conditionally only when Total_Amount__c >= 10000.

<?xml version="1.0" encoding="UTF-8"?>
<FlexiPage xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>Primary Lightning Record Page for Invoice__c with conditional high-value summary card.</description>
    <flexiPageRegions>
        <itemInstances>
            <componentInstance>
                <componentInstanceProperties>
                    <name>collapsed</name>
                    <value>false</value>
                </componentInstanceProperties>
                <componentName>force:highlightsPanel</componentName>
                <identifier>force_highlightsPanel</identifier>
            </componentInstance>
        </itemInstances>
        <name>header</name>
        <type>Region</type>
    </flexiPageRegions>
    <flexiPageRegions>
        <itemInstances>
            <componentInstance>
                <componentInstanceProperties>
                    <name>maxRows</name>
                    <value>10</value>
                </componentInstanceProperties>
                <componentInstanceProperties>
                    <name>showOverdueOnly</name>
                    <value>true</value>
                </componentInstanceProperties>
                <componentName>c:invoiceSummary</componentName>
                <identifier>c_invoiceSummary_highValue</identifier>
                <visibilityRule>
                    <criteria>
                        <leftValue>{!Record.Total_Amount__c}</leftValue>
                        <operator>GE</operator>
                        <rightValue>10000</rightValue>
                    </criteria>
                </visibilityRule>
            </componentInstance>
        </itemInstances>
        <name>main</name>
        <type>Region</type>
    </flexiPageRegions>
    <masterLabel>Invoice Record Page</masterLabel>
    <sobjectType>Invoice__c</sobjectType>
    <template>
        <name>flexipage:recordHomeSingleColTemplateDesktop</name>
    </template>
    <type>RecordPage</type>
</FlexiPage>

Deploy the FlexiPage alongside the CustomObject view override to activate it in a single CLI command:

sf project deploy start \
  --metadata FlexiPage:Invoice_Record_Page CustomObject:Invoice__c \
  --target-org UATSandbox

Limits and Gotchas#

• identifier Uniqueness (API v53.0+): Every <componentInstance> on a FlexiPage requires a unique <identifier> (≤120 characters) within that page. Duplicate identifiers cause deployment errors when hand-copying XML blocks.
• Maximum Components Warning: Pages with more than 25–30 complex components degrade client-side Largest Contentful Paint (LCP). Place heavy related lists or custom LWCs inside non-default tabs (flexipage:tabset) so Salesforce lazy-loads them only when the user clicks the tab.
• Namespace Prefix Retention: Always keep managed package namespace prefixes on fields (ns__Field__c) inside Dynamic Forms <fieldInstance> and <visibilityRule> nodes to avoid name collisions.

Related Official Documentation#

• FlexiPage Metadata API Reference: Complete XML specification for FlexiPage, ComponentInstance, and UiFormulaRule.
• FlexiPage Tooling API Object: Querying Lightning pages via Tooling API.

Frequently asked questions

Why is my FlexiPage not visible to users after deploying the .flexipage-meta.xml file?

Deploying a FlexiPage file only creates or updates the page definition in Lightning App Builder. To activate it, you must also deploy the View actionOverrides in the CustomObject (for org-wide default), CustomApplication (for app defaults), or Profile.

How are Dynamic Forms stored inside a FlexiPage XML file?

Dynamic Forms replace the monolithic force:detailPanel component with flexiPageRegions of type Facet containing fieldInstances (individual fields with visibilityRules and uiBehavior) and flexipage:fieldSection components.

Why did my FlexiPage XML structure change from value to valueList when retrieved on API v49.0+?

Starting in API version 49.0, any array property on a ComponentInstance is serialized as a valueList containing valueListItems instead of a comma-separated value string.

Can I deploy EmailTemplatePage or EmailContentPage FlexiPages via Metadata API?

No. FlexiPages with a type of EmailTemplatePage or EmailContentPage contain internal email builder markup and cannot be retrieved or deployed directly via the FlexiPage metadata type.

How do I query FlexiPage definitions and their associated objects using SOQL?

Use the Tooling API (--use-tooling-api) to query the FlexiPage object: SELECT DeveloperName, MasterLabel, Type, EntityDefinition.QualifiedApiName, LastModifiedDate FROM FlexiPage WHERE Type = 'RecordPage'.