extensionCommonCustomGroupControlsItem object

Configures the buttons and menus in the group.

Properties that reference this object type:

Properties that reference this object type:

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},
  "visible": {boolean},
  "items": [
    {
      "id": "{string}",
      "type": "menuItem",
      "label": "{string}",
      "icons": [
        {
          extensionCommonIcon object
        }
      ],
      "supertip": {
        extensionCommonSuperToolTip object
      },
      "actionId": "{string}",
      "enabled": {boolean},
      "overriddenByRibbonApi": {boolean},
      "keytip": "{string}"
    }
  ],
  "keytip": "{string}"
}

{
  "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},
      "keytip": "{string}"
    }
  ],
  "visible": {boolean},
  "keytip": "{string}"
}

{
  "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},
      "keytip": "{string}"
    }
  ],
  "keytip": "{string}"
}

{
  "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},
      "keytip": "{string}"
    }
  ],
  "keytip": "{string}"
}

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

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

Properties

id

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

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.

Important

This property can't be combined with any other child properties of the control object because built-in controls aren't 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.

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

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: 3. Maximum array items: 8.

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.

The purpose of this property is to create a fallback experience in an add-in that implements custom contextual tabs when the add-in is running on an application or platform that doesn't support custom contextual tabs. The essential strategy is that you duplicate some or all of the groups and controls from your custom contextual tab onto a custom core tab (that is, noncontextual custom tab). Then, to ensure that these groups and controls appear when custom contextual tabs aren't supported, but don't appear when custom contextual tabs are supported, you set overriddenByRibbonApi to true for a parent groups, controls, or menu items properties. The effect of doing so is the following:

  • If the add-in runs on an application and platform that support custom contextual tabs, then the duplicated groups and controls won't appear on the ribbon. Instead, the custom contextual tab will be installed when the add-in calls the requestCreateControls method.
  • If the add-in runs on an application or platform that doesn't support custom contextual tabs, then the duplicated groups and controls will appear on the ribbon.

Note

For a full understanding of this property, see Implement an alternate UI experience when custom contextual tabs aren't supported.

Type
boolean

Required
—

Constraints

Supported values
Default value: false.

enabled

Indicates whether the control is initially enabled. For more information, see Change the availability of add-in commands.

Note

This property isn't supported in Outlook add-ins.

Type
boolean

Required
—

Constraints

Supported values
Default value: True.

visible

Controls whether the control is visible.

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

Supported values

items

Configures the items for a menu control.

Type
Array of extensionCommonCustomControlMenuItem

Required
—

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

Supported values

keytip

KeyTip shortcut for keyboard navigation (1-3 uppercase alphanumeric characters)

Type
string

Required
—

Constraints
Minimum string length: 1. Maximum string length: 3.

Supported values
The string must match the following regular expression: ^[A-Z0-9]+$.

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"
      }
    ]
}
  • Last updated on