extensionCommonCustomGroupControlsItem object

Configures the buttons and menus in the group.

Properties that reference this object type:

• root.extensions.contextMenus.menus.controls
• root.extensions.ribbons.tabs.groups.controls

Properties that reference this object type:

• root.extensions.ribbons.tabs.groups.controls

Syntax

Syntax

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

Schema

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "description": "A unique identifier for this control within the app. Maximum length is 64 characters. ",
      "maxLength": 64
    },
    "type": {
      "type": "string",
      "description": "Defines the type of control whether button or menu.",
      "enum": [
        "button",
        "menu"
      ]
    },
    "builtInControlId": {
      "type": "string",
      "description": "Id of the existing office control. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "label": {
      "type": "string",
      "description": "Displayed text for the control. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "icons": {
      "type": "array",
      "minItems": 1,
      "maxItems": 3,
      "items": {
        "$ref": "#/definitions/extensionCommonIcon"
      }
    },
    "supertip": {
      "$ref": "#/definitions/extensionCommonSuperToolTip"
    },
    "actionId": {
      "type": "string",
      "description": "The ID of an execution-type action that handles this key combination. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "overriddenByRibbonApi": {
      "type": "boolean",
      "description": "Specifies whether a group, button, menu, or menu item will be hidden on application and platform combinations that support the API (Office.ribbon.requestCreateControls) that installs custom contextual tabs on the ribbon. Default is false.",
      "default": "false"
    },
    "enabled": {
      "type": "boolean",
      "description": "Whether the control is initially enabled.",
      "default": true
    },
    "items": {
      "type": "array",
      "description": "Configures the items for a menu control.",
      "minItems": 1,
      "maxItems": 20,
      "items": {
        "$ref": "#/definitions/extensionCommonCustomControlMenuItem"
      }
    }
  },
  "required": [
    "id",
    "type",
    "label",
    "icons",
    "supertip"
  ]
}

Syntax

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

Schema

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "description": "A unique identifier for this control within the app. Maximum length is 64 characters. ",
      "maxLength": 64
    },
    "type": {
      "type": "string",
      "description": "Defines the type of control whether button or menu.",
      "enum": [
        "button",
        "menu"
      ]
    },
    "builtInControlId": {
      "type": "string",
      "description": "Id of the existing office control. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "label": {
      "type": "string",
      "description": "Displayed text for the control. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "icons": {
      "type": "array",
      "minItems": 1,
      "maxItems": 3,
      "items": {
        "$ref": "#/definitions/extensionCommonIcon"
      }
    },
    "supertip": {
      "$ref": "#/definitions/extensionCommonSuperToolTip"
    },
    "actionId": {
      "type": "string",
      "description": "The ID of an execution-type action that handles this key combination. Maximum length is 64 characters.",
      "maxLength": 64
    },
    "overriddenByRibbonApi": {
      "type": "boolean",
      "description": "Specifies whether a group, button, menu, or menu item will be hidden on application and platform combinations that support the API (Office.ribbon.requestCreateControls) that installs custom contextual tabs on the ribbon. Default is false.",
      "default": "false"
    },
    "enabled": {
      "type": "boolean",
      "description": "Whether the control is initially enabled.",
      "default": true
    },
    "items": {
      "type": "array",
      "description": "Configures the items for a menu control.",
      "minItems": 1,
      "maxItems": 20,
      "items": {
        "$ref": "#/definitions/extensionCommonCustomControlMenuItem"
      }
    }
  },
  "required": [
    "id",
    "type",
    "label",
    "icons",
    "supertip",
    "actionId"
  ]
}

Properties

id

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

Type
string

Required
✅

Constraints
Maximum string length: 64.

Supported values

type

Defines the control type.

Type
string

Required
✅

Constraints

Supported values
Allowed values: button, menu.

builtInControlId

Specifies the ID of an existing Microsoft 365 control. 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 control object because built-in controls are not customizable by an add-in.

Type
string

Required
—

Constraints
Maximum string length: 64.

Supported values

label

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

Defines the icons for the control. There must be at least three child objects; one each with size properties of 16, 32, and 80 pixels.

Type
Array of extensionCommonIcon

Required
✅

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

Supported values

supertip

Configures a supertip for the control. A supertip is a UI feature that displays a brief box of help information about a control when the cursor hovers over it. The box may contain multiple lines of text.

Type
extensionCommonSuperToolTip

Required
✅

Constraints

Supported values

actionId

Required if the control type is button. Don't use if the control type is menu. Specifies the ID of the action that is taken when a user selects the control. The actionId must match the runtime.actions.id property of an action in the runtimes object.

Type
string

Required
—

Constraints
Maximum string length: 64.

Supported values

actionId

Required if the control type is button. Don't use if the control type is menu. Specifies the ID of the action that is taken when a user selects the control. The actionId must match the runtime.actions.id property of an action in the runtimes object.

Type
string

Required
✅

Constraints
Maximum string length: 64.

Supported values

overriddenByRibbonApi

Specifies whether the control is hidden on application and platform combinations which support the API (Office.ribbon.requestCreateControls). This API installs custom contextual tabs on the ribbon.

Type
boolean

Required
—

Constraints

Supported values
Default value: false.

enabled

Indicates whether the control is initially enabled.

Type
boolean

Required
—

Constraints

Supported values
Default value: True.

items

Configures the items for a menu control.

Type
Array of extensionCommonCustomControlMenuItem

Required
—

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

Supported values

Examples

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