extensionRibbonsArrayTabsItem object

Configures the custom tabs on the Microsoft 365 application ribbon.

Properties that reference this object type:

• root.extensions.ribbons.tabs

Syntax

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}"
    }
  ],
  "customMobileRibbonGroups": [
    {
      "id": "{string}",
      "label": "{string}",
      "controls": [
        {
          extensionRibbonsCustomMobileControlButtonItem object
        }
      ]
    }
  ]
}

Schema

{
  "type": "object",
  "minProperties": 1,
  "properties": {
    "id": {
      "type": "string",
      "description": "A unique identifier for this tab within the app. Maximum length is 64 characters. ",
      "maxLength": 64
    },
    "label": {
      "type": "string",
      "description": "Displayed text for the tab. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "position": {
      "type": "object",
      "properties": {
        "builtInTabId": {
          "type": "string",
          "description": "The id of the built-in tab. Maximum length is 64 characters.",
          "maxLength": 64
        },
        "align": {
          "type": "string",
          "description": "Define alignment of this custom tab relative to the specified built-in tab.",
          "enum": [
            "after",
            "before"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "builtInTabId",
        "align"
      ]
    },
    "builtInTabId": {
      "type": "string",
      "description": "Id of the existing office Tab. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "groups": {
      "type": "array",
      "minItems": 1,
      "maxItems": 10,
      "description": "Defines tab groups.",
      "items": {
        "$ref": "#/definitions/extensionRibbonsCustomTabGroupsItem"
      }
    },
    "customMobileRibbonGroups": {
      "type": "array",
      "minItems": 1,
      "maxItems": 10,
      "description": "Defines mobile group item.",
      "items": {
        "$ref": "#/definitions/extensionRibbonsCustomMobileGroupItem"
      }
    }
  },
  "dependencies": {
    "builtInTabId": {
      "properties": {
        "groups": {
          "type": "array",
          "maxItems": 10,
          "items": {
            "$ref": "#/definitions/extensionCommonCustomGroup"
          }
        }
      },
      "required": [
        "builtInTabId"
      ]
    },
    "id": {
      "required": [
        "id",
        "label",
        "groups"
      ]
    }
  },
  "additionalProperties": false
}

Properties

id

Specifies the ID for the tab within the app.

Type
string

Required
—

Constraints
Maximum string length: 64.

Supported values

label

Specifies the text displayed for the 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.

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. 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

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"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}