ActionOverride Metadata Type in SFDX

Architectural Overview#

The ActionOverride metadata type configures overrides for standard Salesforce object buttons and navigation entry points (Accept, Clone, Delete, Edit, List, New, Tab, and View). Rather than living in its own standalone folder, ActionOverride is an embedded metadata sub-type declared inside <actionOverrides> tags on CustomObject (.object-meta.xml) or CustomApplication (.app-meta.xml) files.

Understanding ActionOverride is essential for Salesforce Architects because activating a Lightning Record Page in Lightning App Builder at the Org Default or App Default level modifies the target .object-meta.xml or .app-meta.xml file by inserting <actionOverrides> blocks. Failing to commit these <actionOverrides> blocks is the #1 reason newly deployed FlexiPage record pages do not appear for end users in production.

Directory and File Conventions#

ActionOverride elements are embedded directly inside the parent object or application metadata file.

Key Metadata Fields#

Each <actionOverrides> block supports the following XML properties in API version 68.0:

Declarative XML and Package Manifest Examples#

The following Invoice__c.object-meta.xml excerpt configures Org Default View overrides for both Desktop (Large) and Mobile (Small) using a FlexiPage, plus a custom New override using a Lightning component:

<?xml version="1.0" encoding="UTF-8"?>
<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
    <actionOverrides>
        <actionName>View</actionName>
        <comment>Org default desktop Lightning Record Page</comment>
        <content>Invoice_Record_Page</content>
        <formFactor>Large</formFactor>
        <skipRecordTypeSelect>false</skipRecordTypeSelect>
        <type>Flexipage</type>
    </actionOverrides>
    <actionOverrides>
        <actionName>View</actionName>
        <comment>Org default mobile Lightning Record Page</comment>
        <content>Invoice_Record_Page</content>
        <formFactor>Small</formFactor>
        <skipRecordTypeSelect>false</skipRecordTypeSelect>
        <type>Flexipage</type>
    </actionOverrides>
    <actionOverrides>
        <actionName>New</actionName>
        <comment>Custom guided wizard for new invoices</comment>
        <content>c:invoiceCreationWizard</content>
        <formFactor>Large</formFactor>
        <skipRecordTypeSelect>true</skipRecordTypeSelect>
        <type>LightningComponent</type>
    </actionOverrides>
    <deploymentStatus>Deployed</deploymentStatus>
    <label>Invoice</label>
    <nameField>
        <displayFormat>INV-{00000}</displayFormat>
        <label>Invoice Number</label>
        <type>AutoNumber</type>
    </nameField>
    <pluralLabel>Invoices</pluralLabel>
    <sharingModel>Private</sharingModel>
</CustomObject>

Package Manifest (package.xml)#

Because ActionOverride is embedded inside CustomObject, retrieve and deploy the parent CustomObject alongside its target FlexiPage:

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

CLI Retrieval and Deployment Commands#

Use Salesforce CLI to deploy the parent object file containing your <actionOverrides>:

# Retrieve the CustomObject root file and target FlexiPage together
sf project retrieve start --metadata CustomObject:Invoice__c FlexiPage:Invoice_Record_Page

# Deploy only the object-meta.xml file to activate the ActionOverride
sf project deploy start --source-dir force-app/main/default/objects/Invoice__c/Invoice__c.object-meta.xml

Architect Best Practices and Gotchas#

• Missing <actionOverrides> in Git: When developers build a new FlexiPage and click Activate -> Assign as Org Default in Setup, Salesforce mutates <Object>.object-meta.xml. Always retrieve and commit .object-meta.xml alongside .flexipage-meta.xml.
• Infinite Redirect Loops in Edit / New Overrides: When overriding New or Edit with a Lightning component, using lightning/navigation to navigate back to standard__objectPage (actionName: 'new') triggers the override again. Use the nooverride=1 state parameter when falling back to standard modals.

Frequently asked questions

Where is ActionOverride defined in SFDX source format?

ActionOverride is not a standalone top-level file; it is defined inside the actionOverrides element of an object's .object-meta.xml file or inside a Profile or Lightning Application.

Which standard actions can be overridden using ActionOverride?

You can override eight standard actions: Accept, Clone, Delete, Edit, List, New, Tab, and View, depending on the target object and override type.

Can Lightning Web Components directly override standard New or Edit buttons?

In API version 68.0, LWC components that implement the lightning__actionOverride target can directly override View, New, and Edit actions on mobile and desktop form factors.

How does formFactor affect ActionOverride behavior?

Setting formFactor to Large applies the override to desktop Lightning Experience, Small applies it to Salesforce Mobile, and omitting formFactor applies to Classic or default contexts.