CustomTab Metadata Type Reference

The CustomTab metadata type creates a navigation entry in the App Launcher and CustomApplication navigation bars. Available in API version 10.0 and later, a CustomTab can expose a CustomObject home/list view, a standalone LightningComponentBundle (lwcComponent), a Lightning App Page (FlexiPage), a Visualforce page, or an external web url.

In Salesforce DX projects, custom tabs are stored in force-app/main/default/tabs/ with the .tab-meta.xml suffix.

Key Metadata Fields#

Exactly one of customObject, lwcComponent, flexiPage, auraComponent, page, scontrol, or url must be specified per CustomTab:

Production-Grade XML Examples#

1. Custom Object Tab (Invoice__c.tab-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">
    <customObject>true</customObject>
    <description>Primary navigation tab for Customer Invoices.</description>
    <motif>Custom41: Cash</motif>
</CustomTab>

2. Standalone Lightning Web Component Tab (Order_Command_Center.tab-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>Full-screen LWC command center for monitoring real-time ERP order sync queues.</description>
    <label>Order Command Center</label>
    <lwcComponent>orderCommandCenterApp</lwcComponent>
    <motif>Custom67: Gears</motif>
</CustomTab>

Querying Tabs with SOQL (TabDefinition)#

You can inspect all standard and custom tabs available in your org using the TabDefinition object:

-- List all Custom Tabs in the org and their SObject or URL bindings
SELECT Id, Name, Label, SobjectName, IsCustom, Url
FROM TabDefinition
WHERE IsCustom = true
ORDER BY Label ASC

Frequently asked questions

How is a CustomTab for a Custom Object named?

For a Custom Object tab, the file name and fullName must exactly match the API name of the custom object (for example, Invoice__c.tab-meta.xml) and the customObject boolean tag must be set to true.

How do I expose a Lightning Web Component directly as a CustomTab?

Add the lightning__Tab target to the LWC's .js-meta.xml file, then create a CustomTab file where the lwcComponent tag is set to the developer name of your LWC bundle.

Can a single CustomTab reference both a customObject and a flexiPage?

No. Exactly one target field can be populated on a CustomTab: customObject, lwcComponent, flexiPage, auraComponent, page (Visualforce), scontrol, or url.

Why is my deployed CustomTab not visible in the App Launcher?

Deploying a CustomTab creates the tab definition, but users cannot see it until tabVisibilities (PermissionSet) or tabSettings (Profile) is set to DefaultOn or Available (Visible) for that tab.

What is the motif field on a CustomTab?

The motif field is a required string (such as Custom53: Bell or Custom67: Gears) that specifies the icon and color theme for the tab.