Share via

extensionRibbonsArray object

The extensions.ribbons property provides the ability to add add-in commands (buttons and menu items) to the Microsoft 365 application's ribbon. The ribbon definition is selected from the array based on the requirements and first-of order.

Properties that reference this object type:

Syntax

{
  "requirements": {
    "capabilities": [
      {
        capabilities object
      }
    ],
    "scopes": [
      "mail | workbook | document | presentation"
    ],
    "formFactors": [
      "desktop | mobile"
    ]
  },
  "contexts": [
    "mailRead | mailCompose | meetingDetailsOrganizer | meetingDetailsAttendee | onlineMeetingDetailsOrganizer | logEventMeetingDetailsAttendee | default | spamReportingOverride"
  ],
  "tabs": [
    {
      "id": "{string}",
      "label": "{string}",
      "position": {
        position object
      },
      "builtInTabId": "{string}",
      "groups": [
        {
          extensionRibbonsCustomTabGroupsItem object
        }
      ],
      "customMobileRibbonGroups": [
        {
          extensionRibbonsCustomMobileGroupItem object
        }
      ],
      "keytip": "{string}"
    }
  ],
  "fixedControls": [
    {
      "id": "{string}",
      "type": "button",
      "label": "{string}",
      "icons": [
        {
          extensionCommonIcon object
        }
      ],
      "supertip": {
        extensionCommonSuperToolTip object
      },
      "actionId": "{string}",
      "enabled": {boolean}
    }
  ],
  "spamPreProcessingDialog": {
    "title": "{string}",
    "description": "{string}",
    "spamNeverShowAgainOption": {boolean},
    "spamReportingOptions": {
      spamReportingOptions object
    },
    "spamFreeTextSectionTitle": "{string}",
    "spamMoreInfo": {
      spamMoreInfo object
    }
  }
}

{
  "requirements": {
    "capabilities": [
      {
        capabilities object
      }
    ],
    "scopes": [
      "mail | workbook | document | presentation"
    ],
    "formFactors": [
      "desktop | mobile"
    ]
  },
  "contexts": [
    "mailRead | mailCompose | meetingDetailsOrganizer | meetingDetailsAttendee | onlineMeetingDetailsOrganizer | logEventMeetingDetailsAttendee | default | spamReportingOverride"
  ],
  "tabs": [
    {
      "id": "{string}",
      "label": "{string}",
      "position": {
        position object
      },
      "builtInTabId": "{string}",
      "groups": [
        {
          extensionRibbonsCustomTabGroupsItem object
        }
      ],
      "customMobileRibbonGroups": [
        {
          extensionRibbonsCustomMobileGroupItem object
        }
      ]
    }
  ],
  "fixedControls": [
    {
      "id": "{string}",
      "type": "button",
      "label": "{string}",
      "icons": [
        {
          extensionCommonIcon object
        }
      ],
      "supertip": {
        extensionCommonSuperToolTip object
      },
      "actionId": "{string}",
      "enabled": {boolean}
    }
  ],
  "spamPreProcessingDialog": {
    "title": "{string}",
    "description": "{string}",
    "spamNeverShowAgainOption": {boolean},
    "spamReportingOptions": {
      spamReportingOptions object
    },
    "spamFreeTextSectionTitle": "{string}",
    "spamMoreInfo": {
      spamMoreInfo object
    }
  }
}

{
  "requirements": {
    "capabilities": [
      {
        capabilities object
      }
    ],
    "scopes": [
      "mail | workbook | document | presentation"
    ],
    "formFactors": [
      "desktop | mobile"
    ]
  },
  "contexts": [
    "mailRead | mailCompose | meetingDetailsOrganizer | meetingDetailsAttendee | onlineMeetingDetailsOrganizer | logEventMeetingDetailsAttendee | default | spamReportingOverride"
  ],
  "tabs": [
    {
      "id": "{string}",
      "label": "{string}",
      "position": {
        position object
      },
      "builtInTabId": "{string}",
      "groups": [
        {
          extensionRibbonsCustomTabGroupsItem object
        }
      ],
      "customMobileRibbonGroups": [
        {
          extensionRibbonsCustomMobileGroupItem object
        }
      ]
    }
  ],
  "fixedControls": [
    {
      "id": "{string}",
      "type": "button",
      "label": "{string}",
      "icons": [
        {
          extensionCommonIcon object
        }
      ],
      "supertip": {
        extensionCommonSuperToolTip object
      },
      "actionId": "{string}",
      "enabled": {boolean}
    }
  ],
  "spamPreProcessingDialog": {
    "title": "{string}",
    "description": "{string}",
    "spamReportingOptions": {
      spamReportingOptions object
    },
    "spamFreeTextSectionTitle": "{string}",
    "spamMoreInfo": {
      spamMoreInfo object
    }
  }
}

{
  "requirements": {
    "capabilities": [
      {
        capabilities object
      }
    ],
    "scopes": [
      "mail | workbook | document | presentation"
    ],
    "formFactors": [
      "desktop | mobile"
    ]
  },
  "contexts": [
    "mailRead | mailCompose | meetingDetailsOrganizer | meetingDetailsAttendee | onlineMeetingDetailsOrganizer | logEventMeetingDetailsAttendee | default"
  ],
  "tabs": [
    {
      "id": "{string}",
      "label": "{string}",
      "position": {
        position object
      },
      "builtInTabId": "{string}",
      "groups": [
        {
          extensionRibbonsCustomTabGroupsItem object
        }
      ],
      "customMobileRibbonGroups": [
        {
          extensionRibbonsCustomMobileGroupItem object
        }
      ]
    }
  ]
}

Properties

requirements

Specifies the scopes, formFactors, and Office JavaScript library requirement sets that must be supported on the Office client in order for the ribbon customization to appear. For more information, see Specify Office Add-in requirements in the unified manifest for Microsoft 365.

Type
requirementsExtensionElement

Required
—

Constraints

Supported values

contexts

Specifies the Microsoft 365 application window in which the ribbon customization is available to the user. Each item in the array is a member of a string array.

The following values are supported.

  • default: Adds add-in commands to the ribbon. Applies to Excel, PowerPoint, and Word.
  • mailRead: Adds add-in commands to the ribbon of a message in read mode. Applies to Outlook only.
  • mailCompose: Adds add-in commands to the ribbon of a message in compose mode. Applies to Outlook only.
  • meetingDetailsOrganizer: Adds add-in commands to the ribbon of an appointment being composed by a meeting organizer. Applies to Outlook only.
  • meetingDetailsAttendee: Adds add-in commands to the ribbon of an appointment that's displayed to a meeting attendee. Applies to Outlook only.
  • onlineMeetingDetailsOrganizer: Adds an online-meeting provider toggle to an appointment being composed by a meeting organizer in Outlook on mobile devices. For more information, see Create an Outlook add-in for an online-meeting provider.
  • logEventMeetingDetailsAttendee: Adds a Log button to an appointment that's displayed to a meeting attendee in Outlook on mobile devices. For more information, see Log appointment notes to an external application in Outlook mobile add-ins.
  • spamReportingOverride: Adds the button of a spam-reporting add-in to a prominent spot on the ribbon of the Outlook client. Prevents the add-in button from appearing at the end of the ribbon or in the overflow menu. For more information, see Implement an integrated spam-reporting add-in.

Type
Array of string

Required
—

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

Supported values
Allowed values: mailRead, mailCompose, meetingDetailsOrganizer, meetingDetailsAttendee, onlineMeetingDetailsOrganizer, logEventMeetingDetailsAttendee, default, spamReportingOverride.

contexts

Specifies the Microsoft 365 application window in which the ribbon customization is available to the user. Each item in the array is a member of a string array.

Type
Array of string

Required
—

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

Supported values
Allowed values: mailRead, mailCompose, meetingDetailsOrganizer, meetingDetailsAttendee, onlineMeetingDetailsOrganizer, logEventMeetingDetailsAttendee, default, spamReportingOverride.

contexts

Specifies the Microsoft 365 application window in which the ribbon customization is available to the user. Each item in the array is a member of a string array.

Type
Array of string

Required
—

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

Supported values
Allowed values: mailRead, mailCompose, meetingDetailsOrganizer, meetingDetailsAttendee, onlineMeetingDetailsOrganizer, logEventMeetingDetailsAttendee, default.

tabs

Configures custom tabs or customized built-in tabs on the Office application ribbon.

Type
Array of extensionRibbonsArrayTabsItem

Required
✅

Constraints
Maximum array items: 20.

Supported values

fixedControls

Configures the button of an integrated spam-reporting add-in in Outlook. Must configure if spamReportingOverride is specified in the extensions.ribbons.contexts array.

Type
Array of extensionRibbonsArrayFixedControlItem

Required
—

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

Supported values

fixedControls

Configures the button of an integrated spam-reporting add-in in Outlook. Must configure if spamReportingOverride is specified in the extensions.ribbons.contexts array.

Type
Array of extensionRibbonsArrayFixedControlItem

Required
—

Constraints

Supported values

spamPreProcessingDialog

Configures the preprocessing dialog of an integrated spam-reporting add-in in Outlook.

Type
extensionRibbonsSpamPreProcessingDialog

Required
—

Constraints

Supported values

Remarks

To use extensions.ribbons, see create add-in commands, configure the UI for the task pane command, and configure the UI for the function command.

Examples

{
 "extensions": [
    {
      "ribbons": [
        {
          "contexts": [
            "mailCompose"
          ],
          "tabs": [
            {
              "builtInTabId": "TabDefault",
              "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"
                    },
                    {
                      "id": "menu1",
                      "type": "menu",
                      "label": "My Menu",
                      "icons": [
                        {
                          "size": 16,
                          "url": "test_16.png"
                        },
                        {
                          "size": 32,
                          "url": "test_32.png"
                        },
                        {
                          "size": 80,
                          "url": "test_80.png"
                        }
                      ],
                      "supertip": {
                        "title": "My Menu",
                        "description": "Menu with 2 actions"
                      },
                      "items": [
                        {
                          "id": "menuItem1",
                          "type": "menuItem",
                          "label": "Action 2",
                          "supertip": {
                            "title": "Action 2 Title",
                            "description": "Action 2 Description"
                          },
                          "actionId": "action2"
                        },
                        {
                          "id": "menuItem2",
                          "type": "menuItem",
                          "label": "Action 3",
                          "icons": [
                            {
                              "size": 16,
                              "url": "test_16.png"
                            },
                            {
                              "size": 32,
                              "url": "test_32.png"
                            },
                            {
                              "size": 80,
                              "url": "test_80.png"
                            }
                          ],
                          "supertip": {
                            "title": "Action 3 Title",
                            "description": "Action 3 Description"
                          },
                          "actionId": "action3"
                        }
                      ]
                    }
                  ]
                }
              ],
            }
          ]
        },
        {
          "contexts": [ "mailRead" ],
          "tabs": [
            {
              "builtInTabId": "TabDefault",
              "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"
                    }
                  ]
                }
              ],
              "customMobileRibbonGroups" [
                {
                  "id": "myMobileGroup",
                  "label": "Contoso Actions",
                  "controls": [
                    {
                      "id": "msgReadFunctionButton",
                      "type": "mobileButton",
                      "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"
                    }
                  ]
                }
              ]
              "customMobileRibbonGroups": [
                {
                  "id": "mobileDashboard",
                  "label": "Controls",
                  "controls": [
                    {
                      "id": "control1",
                      "type": "mobileButton",
                      "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