Edit

CustomTab element

  • Article

Defines a custom tab for the Office ribbon. Add ribbon controls and groups for the add-in either to one of the build-in Office tabs or to your own custom tab. Use the <CustomTab> element to add a custom tab to the ribbon. On custom tabs, the add-in can have custom or built-in groups. Add-ins are limited to one custom tab.

Important

In Outlook on Mac, the <CustomTab> element is not available, but you can put custom groups of controls on one of the built-in OfficeTabs instead. You cannot put built-in groups on built-in tabs in Outlook on any platform.

Add-in type: Task pane, Mail

Valid only in these VersionOverrides schemas:

  • Task pane 1.0
  • Mail 1.0
  • Mail 1.1

For more information, see Version overrides in the manifest.

Note

Some child elements are not valid in the Mail schemas. See Child elements.

Associated with these requirement sets:

Attributes

Attribute Required Description
id Yes A unique ID for the custom tab.

id attribute

Required. Unique identifier for the custom tab. It is a string with a maximum of 125 characters. This must be unique within the manifest.

Child elements

Element Required Description
Group No Defines a Group of commands.
OfficeGroup No Represents a built-in Office control group. Important: Not available in Outlook.
Label Yes The label for the CustomTab.
InsertAfter No Specifies that the custom tab should be immediately after a specified built-in Office tab. Important: Only available in PowerPoint.
InsertBefore No Specifies that the custom tab should be immediately before a specified built-in Office tab. Important: Only available in PowerPoint.

Group

Optional, but if not present there must be at least one <OfficeGroup> element. See Group element. The order of <Group> and <OfficeGroup> in the manifest should be the order you want them to appear on the custom tab. They can be intermingled if there are multiple elements, but all must be above the <Label> element.

OfficeGroup

Optional, but if not present there must be at least one <Group> element. Represents a built-in Office control group. The id attribute specifies the ID of the built-in Office group. To find the ID of a built-in group, see Find the IDs of controls and control groups. The order of <Group> and <OfficeGroup> in the manifest should be the order you want them to appear on the custom tab. They can be intermingled if there are multiple elements, but all must be above the <Label> element.

Important

The <OfficeGroup> element is not available in Outlook. In PowerPoint, it is in preview for Mac and Windows; but is available for production add-ins in PowerPoint on the web.

Add-in type: Task pane

Valid only in these VersionOverrides schemas:

  • Task pane 1.0

For more information, see Version overrides in the manifest.

Associated with these requirement sets:

Label (Tab)

Required. The label of the custom tab. The resid attribute can be no more than 32 characters and must be set to the value of the id attribute of a <String> element in the <ShortStrings> element in the Resources element.

Add-in type: Task pane, Mail

Valid only in these VersionOverrides schemas:

  • Task pane 1.0
  • Mail 1.0
  • Mail 1.1

For more information, see Version overrides in the manifest.

Associated with these requirement sets:

InsertAfter

Optional. Specifies that the custom tab should be immediately after a specified built-in Office tab. The value of the element is the ID of the built-in tab, such as TabHome or TabReview. For a list of built-in tabs, see OfficeTab. If present, must be after the <Label> element. You cannot have both <InsertAfter> and <InsertBefore>.

Important

The <InsertAfter> element is only available in PowerPoint.

Add-in type: Task pane

Valid only in these VersionOverrides schemas:

  • Task pane 1.0

For more information, see Version overrides in the manifest.

Associated with these requirement sets:

InsertBefore

Optional. Specifies that the custom tab should be immediately before a specified built-in Office tab. The value of the element is the ID of the built-in tab, such as TabHome or TabReview. The value of the element is the ID of the built-in tab, such as TabHome or TabReview. For a list of built-in tabs, see OfficeTab. If present, must be after the <Label> element. You cannot have both <InsertAfter> and <InsertBefore>.

Important

The <InsertBefore> element is only available in PowerPoint.

Add-in type: Task pane

Valid only in these VersionOverrides schemas:

  • Task pane 1.0

For more information, see Version overrides in the manifest.

Associated with these requirement sets:

Examples

The following markup example adds the Office Paragraph control group to a custom tab and positions it to appear just after a custom group.

<ExtensionPoint xsi:type="ContosoRibbonTab">
  <CustomTab id="Contoso.TabCustom">
    <Group id="Contoso.TabCustom1.group1">
       <!-- additional markup omitted -->
    </Group>
    <OfficeGroup id="Paragraph" />
    <Label resid="customTabLabel1" />
  </CustomTab>
</ExtensionPoint>

The following markup example adds the Office Superscript control to a custom group and positions it to appear just after a custom button.

<ExtensionPoint xsi:type="ContosoRibbonTab">
  <CustomTab id="Contoso.TabCustom">
    <Group id="Contoso.TabCustom2.group2">
        <Label resid="residCustomTabGroupLabel"/>
        <Icon>
            <bt:Image size="16" resid="blue-icon-16" />
            <bt:Image size="32" resid="blue-icon-32" />
            <bt:Image size="80" resid="blue-icon-80" />
        </Icon>
        <Control xsi:type="Button" id="Contoso.Button2">
            <!-- information on the control omitted -->
        </Control>
        <OfficeControl id="Superscript" />
        <!-- other controls, as needed -->
    </Group>
    <Label resid="customTabLabel1" />
  </CustomTab>
</ExtensionPoint>