Share via

extensionCommonCustomControlMenuItem object

  • Article

Configures the items for a menu control.

Properties that reference this object type:

Properties that reference this object type:

Syntax

{
  "id": "{string}",
  "type": "menuItem",
  "label": "{string}",
  "icons": [
    {
      "size": {number},
      "url": "{string}"
    }
  ],
  "supertip": {
    "title": "{string}",
    "description": "{string}"
  },
  "actionId": "{string}",
  "enabled": {boolean},
  "overriddenByRibbonApi": {boolean}
}

Properties

id

Specifies the ID for a menu item.

Type
string

Required
✅

Constraints
Maximum string length: 64.

Supported values

type

Defines the menu item's control type.

Type
string

Required
✅

Constraints

Supported values
Allowed values: menuItem.

label

Specifies the text displayed for the menu item.

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

Type
string

Required
✅

Constraints
Maximum string length: 64.

Supported values

icons

Configures the icons for the menu item.

Type
Array of extensionCommonIcon

Required
—

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

Supported values

supertip

Configures a supertip for the menu item. 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

Specifies the ID of the action that is taken when a user selects the control or menu item. The actionId must match with some runtimes.actions.id property value.

Type
string

Required
✅

Constraints
Maximum string length: 64.

Supported values

enabled

Indicates whether the menu item is initially enabled.

Note

  • This property isn't supported in Outlook add-ins.
  • This property is supported only in menus on the ribbon, not in a context menu.

Type
boolean

Required
—

Constraints

Supported values
Default value: True.

overriddenByRibbonApi

Specifies whether the menu item 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.

Examples

{
  "items": [
    {
      "id": "menuItem1",
      "type": "menuItem",
      "label": "Action 2",
      "supertip": {
        "title": "Action 2 Title",
        "description": "Action 2 Description"
      },
      "actionId": "action2"
    },
  ]
}