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:
truefor custom object tabs,falsefor 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