When to Use This Skill

Use this skill when you need to:

• Create tabs for objects, web pages, or Visualforce pages

• Add navigation tabs to applications

• Configure tab visibility and access

• Troubleshoot deployment errors related to custom tabs

Specification

CustomTab Metadata Specification

📋 Overview

Custom tabs for navigating to objects, web content, or Visualforce pages within Salesforce applications.

🎯 Purpose

• Provide navigation to custom objects

• Link to external web content

• Access Visualforce pages

• Organize application navigation

⚙️ Required Properties

Core Tab Properties

• customObject: true for custom object tabs, false for all others.

• motif: Tab icon style — choose a motif that semantically matches the object's purpose. Do NOT reuse the same motif for every tab.

• label: Display name (required for non-object tabs ONLY; object tabs inherit label from the object)

• url: Web URL (for web tabs)

• page: Visualforce page name (for Visualforce tabs)

🚨 STRICT ELEMENT ALLOWLIST — READ THIS FIRST

**The root element MUST always be <CustomTab> (NOT <Tab>).** The XML namespace must be xmlns="http://soap.sforce.com/2006/04/metadata".

Only the elements listed below are valid. Any element not on this list WILL cause a deployment error.

Tab Type

ONLY these elements are allowed (nothing else)

Object tabs

<customObject> (required, set to true), <motif> (required), <description> (optional)

Web tabs

<customObject> (required, set to false), <label> (required), <motif> (required), <url> (required), <urlEncodingKey> (required, set to UTF-8), <description> (optional), <frameHeight> (optional)

Visualforce tabs

<customObject> (required, set to false), <label> (required), <motif> (required), <page> (required), <description> (optional)

⚠️ FORBIDDEN ELEMENTS (every one of these causes a deployment error)

<sobjectName>, <name>, <fullName>, <apiVersion>, <isHidden>, <tabVisibility>, <type>, <mobileReady>, <urlFrameHeight>, <urlType>, <urlRedirect>, <encodingKey>, <height>, <auraComponent>

Also forbidden:

• <label> on object tabs (object tabs inherit their label from the custom object)

• <page> on web tabs (only for Visualforce tabs)

• Empty elements like <page></page> or <description></description>

• Any element not in the allowlist table above

🔧 Tab Types

Object Tabs

• Purpose: Navigate to custom or standard objects

• File name determines the object: {ObjectApiName}.tab-meta.xml (e.g., Space_Station__c.tab-meta.xml)

• Required elements: <customObject>true</customObject> and <motif>

• Correct example (for a Space_Station__c.tab-meta.xml):

<?xml version="1.0" encoding="UTF-8"?>

<CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">

    <customObject>true</customObject>

    <motif>Custom39: Telescope</motif>

</CustomTab>

• Correct example (for a Supply__c.tab-meta.xml — note different motif):

<?xml version="1.0" encoding="UTF-8"?>

<CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">

    <customObject>true</customObject>

    <motif>Custom98: Truck</motif>

</CustomTab>

• ❌ WRONG — do NOT add <sobjectName>, <name>, <fullName>, or <label>:

<CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">

    <sobjectName>Space_Station__c</sobjectName>  <!-- DEPLOYMENT ERROR -->

    <label>Space Station</label>                  <!-- DEPLOYMENT ERROR on object tabs -->

    <customObject>true</customObject>

    <motif>Custom57: Desert</motif>

</CustomTab>

Web Tabs

• Purpose: Link to external websites or web applications

• File name: Use a descriptive name: {TabName}.tab-meta.xml (e.g., Knowledge_Base.tab-meta.xml)

• COPY THIS EXACT TEMPLATE — only replace the placeholder values. Do NOT add, remove, or rename any XML elements:

<?xml version="1.0" encoding="UTF-8"?>

<CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">

    <customObject>false</customObject>

    <description>REPLACE_WITH_DESCRIPTION</description>

    <frameHeight>600</frameHeight>

    <label>REPLACE_WITH_LABEL</label>

    <motif>REPLACE_WITH_MOTIF</motif>

    <url>REPLACE_WITH_URL</url>

    <urlEncodingKey>UTF-8</urlEncodingKey>

</CustomTab>

• These 7 elements above are the ONLY elements allowed in a web tab file. Do not add ANY other elements.

• The <description> element is optional — you may remove it if not needed, but do not add anything else.

Visualforce Tabs

• Purpose: Access custom Visualforce pages

• File name: {TabName}.tab-meta.xml (e.g., Custom_Page_Tab.tab-meta.xml)

• Required elements: <customObject>false</customObject>, <label>, <motif>, <page>

• Correct example:

<?xml version="1.0" encoding="UTF-8"?>

<CustomTab xmlns="http://soap.sforce.com/2006/04/metadata">

    <customObject>false</customObject>

    <label>Custom Page</label>

    <motif>Custom46: Computer</motif>

    <page>CustomPage</page>

</CustomTab>

🎨 Tab Configuration

Tab Style

• Default: Use standard tab styling

• Custom: Can specify custom tab styles if needed

Tab Visibility

• Default: Visible to all users with access

• Custom: Can be configured for specific user profiles

📱 Supported Applications

• Standard Apps: Available in standard Salesforce applications

• Custom Apps: Can be included in custom applications

• Community Apps: Available in community applications

🔗 Integration Points

• Object Relationships: Links to related object records

• Web Content: External website integration

• Visualforce Pages: Custom page functionality

• Lightning Components: Modern component integration

✅ Best Practices

• Use clear, descriptive tab labels

• Choose appropriate tab types for functionality

• Select a unique, contextually relevant motif for each tab — do not default every tab to the same icon

• Consider user experience and navigation flow

• Test tab functionality across different applications

• Ensure proper permissions and visibility settings

• Follow consistent naming conventions

• Object tab files MUST only contain <customObject>true</customObject> and <motif> — nothing else

• Web tab files MUST only contain: <customObject>false</customObject>, <label>, <motif>, <url>, <urlEncodingKey>, and optionally <description>, <frameHeight> — nothing else

• Never include <isHidden>, <tabVisibility>, <type>, <mobileReady>, or empty elements