Edit

Share via

Integrate built-in Office buttons into custom control groups and tabs

  • Article

You can insert built-in Office buttons into your custom control groups on the Office ribbon by using markup in the add-in's manifest. (You can't insert your custom add-in commands into a built-in Office group.) You can also insert entire built-in Office control groups into your custom ribbon tabs.

Note

This article assumes that you're familiar with the article Basic concepts for add-in commands. Please review it if you haven't done so recently.

Important

The add-in feature described in this article is only available in PowerPoint on the web, on Windows, and on Mac.

Open the tab for the type of manifest your add-in uses for the details of the manifest markup.

Note

The unified manifest for Microsoft 365 can be used in production Outlook add-ins. It's available only as a preview for Excel, PowerPoint, and Word add-ins.

Insert a built-in control group into a custom tab

To insert a built-in Office control group into a custom tab, add a group object with a "builtInGroupId" property instead of an "id" property to the "groups" array of your custom tab object. Set to the ID of the built-in group. See Find the IDs of controls and control groups. The built-in group object should have no other properties.

The following example adds the Office Paragraph control group to a custom tab.

"extensions": [
    ...
    {
        ...
        "ribbons": [
            ...
            {
                ...
                "tabs": [
                    {
                        "id": "MyTab",
                        ...
                        "groups": [
                            ... // Optionally, other groups in the tab
                            {
                                "builtInGroupId": "Paragraph"
                            },
                            ... // Optionally, other groups in the tab
                        ]
                    }
                ]
            }
        ]
    }
]

Insert a built-in control into a custom group

To insert a built-in Office control into a custom group, add a control object with a "builtInControlId" property instead of an "id" property to the "controls" array of your custom group object. Set to the ID of the built-in control. See Find the IDs of controls and control groups. The built-in control object should have no other properties.

The following example adds the Office Superscript control to a custom group.

"extensions": [
    ...
    {
        ...
        "ribbons": [
            ...
            {
                ...
                "tabs": [
                    {
                        ...
                        "groups": [
                            {
                                "id": "MyGroup",
                                ...
                                "controls": [
                                    ... // Optionally, other controls in the group
                                    {
                                        "builtInControlId": "Superscript"
                                    },
                                    ... // Optionally, other controls in the group
                                ]
                            }
                        ]
                    }
                ]
            }
        ]
    }
]

Note

Users can customize the ribbon in the Office application. Any user customizations will override your manifest settings. For example, a user can remove a button from any group and remove any group from a tab.

Find the IDs of controls and control groups

The IDs for supported controls and control groups are in files in the repo Office Control IDs. Follow the instructions in the ReadMe file of that repo.

Behavior on unsupported platforms

If your add-in is installed on a platform that doesn't support requirement set AddinCommands 1.3, then the markup described in this article is ignored and the built-in Office controls/groups won't appear in your custom groups/tabs. To prevent your add-in from being installed on platforms that don't support the markup, you must specify AddinCommands 1.3 in the manifest as a requirement for installation. For instructions, see Specify which Office versions and platforms can host your add-in. Alternatively, design your add-in to have an experience when AddinCommands 1.3 isn't supported, as described in Design for alternate experiences. For example, if your add-in contains instructions that assume the built-in buttons are in your custom groups, you could design a version that assumes that the built-in buttons are only in their usual places.