extensionRibbonsCustomTabGroupsItem object

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

Properties that reference this object type:

• root.extensions.ribbons.tabs.groups

Syntax

Syntax

{
  "id": "{string}",
  "label": "{string}",
  "icons": [
    {
      "size": {number},
      "url": "{string}"
    }
  ],
  "controls": [
    {
      "id": "{string}",
      "type": "button | menu",
      "builtInControlId": "{string}",
      "label": "{string}",
      "icons": [
        {
          extensionCommonIcon object
        }
      ],
      "supertip": {
        extensionCommonSuperToolTip object
      },
      "actionId": "{string}",
      "overriddenByRibbonApi": {boolean},
      "enabled": {boolean},
      "items": [
        {
          extensionCommonCustomControlMenuItem object
        }
      ]
    }
  ],
  "builtInGroupId": "{string}"
}

Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "A unique identifier for this group within the app. Maximum length is 64 characters. ",
      "maxLength": 64
    },
    "label": {
      "type": "string",
      "description": "Displayed text for the group. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "icons": {
      "type": "array",
      "minItems": 1,
      "maxItems": 3,
      "items": {
        "$ref": "#/definitions/extensionCommonIcon"
      }
    },
    "controls": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/extensionCommonCustomGroupControlsItem"
      },
      "minItems": 1,
      "maxItems": 20
    },
    "builtInGroupId": {
      "type": "string",
      "description": "Id of a built-in Group. Maximum length is 64 characters.",
      "maxLength": 64
    }
  },
  "additionalProperties": false
}

Properties

id

Specifies the ID for the tab group within the app. It must be different from any built-in group ID in the Microsoft 365 application and any other custom group.

Type
string

Required
—

Constraints
Maximum string length: 64.

Supported values

label

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

icons

Specifies the icons displayed for the group.

Type
Array of extensionCommonIcon

Required
—

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

Supported values

controls

Configures the buttons and menus in the group.

Type
Array of extensionCommonCustomGroupControlsItem

Required
—

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

Supported values

builtInGroupId

Specifies the ID of a built-in group. For more information, see find the IDs of controls and control groups. This property can't be combined with any other child properties of the group object because built-in groups are not customizable by an add-in.

Type
string

Required
—

Constraints
Maximum string length: 64.

Supported values

Examples

{
 "extensions": [
    {
      "ribbons": [
        {
          "tabs": [
            {
              "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"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}