Share via

extensionRibbonsArrayTabsItem object

  • Article

Configures a custom tab, or customized built-in tab, on the Office application ribbon. You can include custom and built-in control groups on the tab.

Properties that reference this object type:

Syntax

{
  "id": "{string}",
  "label": "{string}",
  "position": {
    "builtInTabId": "{string}",
    "align": "after | before"
  },
  "builtInTabId": "{string}",
  "groups": [
    {
      "id": "{string}",
      "label": "{string}",
      "icons": [
        {
          extensionCommonIcon object
        }
      ],
      "controls": [
        {
          extensionCommonCustomGroupControlsItem object
        }
      ],
      "builtInGroupId": "{string}",
      "overriddenByRibbonApi": {boolean}
    }
  ],
  "customMobileRibbonGroups": [
    {
      "id": "{string}",
      "label": "{string}",
      "controls": [
        {
          extensionRibbonsCustomMobileControlButtonItem object
        }
      ]
    }
  ]
}

{
  "id": "{string}",
  "label": "{string}",
  "position": {
    "builtInTabId": "{string}",
    "align": "after | before"
  },
  "builtInTabId": "{string}",
  "groups": [
    {
      "id": "{string}",
      "label": "{string}",
      "icons": [
        {
          extensionCommonIcon object
        }
      ],
      "controls": [
        {
          extensionCommonCustomGroupControlsItem object
        }
      ],
      "builtInGroupId": "{string}"
    }
  ],
  "customMobileRibbonGroups": [
    {
      "id": "{string}",
      "label": "{string}",
      "controls": [
        {
          extensionRibbonsCustomMobileControlButtonItem object
        }
      ]
    }
  ]
}

Properties

id

Specifies the ID for a custom tab.

Important

  • If the id property is present, the tabs.label and either the tabs.groups or tabs.customMobileRibbonGroups property must also be present.
  • The tabs.id and tabs.builtInTabId are mutually exclusive. Don't use them both in the same tab object.

Type
string

Required
—

Constraints
Maximum string length: 64.

Supported values

label

Specifies the text displayed for a custom tab. Despite the maximum length of 64 characters, to correctly align the tab in the ribbon, we recommend you limit the label to 16 characters.

This property is localizable. For more information, see the localization schema.

Type
string

Required
—

Constraints
Maximum string length: 64.

Supported values

position

Configures the position of the custom tab relative to other tabs on the ribbon.

Type
position

Required
—

Constraints

Supported values

builtInTabId

Specifies the ID of a built-in Office ribbon tab. For more information on possible values, see Find the IDs of built-in Office ribbon tabs.

Important

The only other child properties of the tab object that can be combined with this one are groups and customMobileRibbonGroups.

Type
string

Required
—

Constraints
Maximum string length: 64.

Supported values

groups

Defines groups of controls on a ribbon tab on a non-mobile device. For mobile devices, see tabs.customMobileRibbonGroups.

Type
Array of extensionRibbonsCustomTabGroupsItem

Required
—

Constraints
Minimum array items: 1. Maximum array items: 10.

Supported values

customMobileRibbonGroups

Defines groups of controls on the default tab of the ribbon on a mobile device. This array property can only be present on tab objects that have a tabs.builtInTabId property that is set to DefaultTab. For non-mobile devices, see tabs.groups above.

Type
Array of extensionRibbonsCustomMobileGroupItem

Required
—

Constraints
Minimum array items: 1. Maximum array items: 10.

Supported values

Remarks

There isn't as much support for custom tabs and customized built-in tabs in Outlook add-ins as there is in other Office applications. Custom tabs are supported in classic Outlook on Windows, but not in Outlook on the web, on Mac, and in the new Outlook on Windows; but you can put custom groups of controls on one of the built-in Office tabs instead. You can't put built-in groups on built-in tabs in Outlook on any platform.

Examples

{
 "extensions": [
    {
      "ribbons": [
        {
          "tabs": [
            {
              "builtInTabId": "TabDefault",
              "groups": [
                {
                  "id": "dashboard",
                  "label": "Controls",
                  "controls": [
                    {
                      "id": "control1",
                      "type": "button",
                      "label": "Action 1",
                      "icons": [
                        {
                          "size": 16,
                          "url": "test_16.png"
                        },
                        {
                          "size": 32,
                          "url": "test_32.png"
                        },
                        {
                          "size": 80,
                          "url": "test_80.png"
                        }
                      ],
                      "supertip": {
                        "title": "Action 1 Title",
                        "description": "Action 1 Description"
                      },
                      "actionId": "action1"
                    }
                  ]
                }
              ],
              "customMobileRibbonGroups" [
                {
                  "id": "myMobileGroup",
                  "label": "Contoso Actions",
                  "controls": [
                    {
                      "id": "msgReadFunctionButton",
                      "type": "mobileButton",
                      "label": "Action 1",
                      "icons": [
                        {
                          "size": 16,
                          "url": "test_16.png"
                        },
                        {
                          "size": 32,
                          "url": "test_32.png"
                        },
                        {
                          "size": 80,
                          "url": "test_80.png"
                        }
                      ],
                      "supertip": {
                        "title": "Action 1 Title",
                        "description": "Action 1 Description"
                      },
                      "actionId": "action1"
                    }
                  ]
                }
              ]
              "customMobileRibbonGroups": [
                {
                  "id": "mobileDashboard",
                  "label": "Controls",
                  "controls": [
                    {
                      "id": "control1",
                      "type": "mobileButton",
                      "label": "Action 1",
                      "icons": [
                        {
                          "size": 16,
                          "url": "test_16.png"
                        },
                        {
                          "size": 32,
                          "url": "test_32.png"
                        },
                        {
                          "size": 80,
                          "url": "test_80.png"
                        }
                      ],
                      "supertip": {
                        "title": "Action 1 Title",
                        "description": "Action 1 Description"
                      },
                      "actionId": "action1"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}