extensionCommonCustomGroupControlsItem object
Configures the buttons and menus in the group.
Properties that reference this object type:
Properties that reference this object type:
{
"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}
}
]
}
{
"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}
}
]
}
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
Defines the control type.
Type
string
Required
✅
Constraints
Supported values
Allowed values: button
, menu
.
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
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
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
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.
Required
✅
Constraints
Supported values
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
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
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
.
Indicates whether the control is initially enabled.
Type
boolean
Required
—
Constraints
Supported values
Default value: True
.
Configures the items for a menu control.
Type
Array of extensionCommonCustomControlMenuItem
Required
—
Constraints
Minimum array items: 1. Maximum array items: 20.
Supported values
{
"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"
}
]
}