Add-in commands for Excel, PowerPoint, and Word
For an overview of the feature, see the video Add-in Commands in the Office app ribbon.
Add-in commands are also supported in Outlook. For more information, see Add-in commands for Outlook.
Figure 1. Add-in with commands running in Excel Desktop
Figure 2. Add-in with commands running in Excel on the web
The following command capabilities are currently supported.
Content add-ins do not currently support add-in commands.
- Ribbon tabs - Extend built-in tabs or create a new custom tab.
- Context menus - Extend selected context menus.
- Simple buttons - trigger specific actions.
- Menus - simple menu dropdown with buttons that trigger actions.
- ShowTaskpane - Displays one or multiple panes that load custom HTML pages inside them.
Default Enabled or Disabled Status
You can specify whether the command is enabled or disabled when your add-in launches, and programmatically change the setting.
This feature is not supported in all Office applications or scenarios. For more information, see Enable and Disable Add-in Commands.
Add-in commands are currently supported on the following platforms.
- Office on Windows (build 16.0.6769+, connected to a Microsoft 365 subscription)
- Office 2019 on Windows
- Office on Mac (build 15.33+, connected to a Microsoft 365 subscription)
- Office 2019 on Mac
- Office on the web
For information about support in Outlook, see Add-in commands for Outlook.
To debug an Add-in Command, you must run it in Office on the web. For details, see Debug add-ins in Office on the web.
Apply the following best practices when you develop add-in commands:
Use commands to represent a specific action with a clear and specific outcome for users. Do not combine multiple actions in a single button.
Provide granular actions that make common tasks within your add-in more efficient to perform. Minimize the number of steps an action takes to complete.
For the placement of your commands in the Office app ribbon:
- Place commands on an existing tab (Insert, Review, and so on) if the functionality provided fits there. For example, if your add-in enables users to insert media, add a group to the Insert tab. Note that not all tabs are available across all Office versions. For more information, see Office Add-ins XML manifest.
- Place commands on the Home tab if the functionality doesn't fit on another tab, and you have fewer than six top-level commands. You can also add commands to the Home tab if your add-in needs to work across Office versions (such as Office on the web or desktop) and a tab is not available in all versions (for example, the Design tab doesn't exist in Office on the web).
- Place commands on a custom tab if you have more than six top-level commands.
- Name your group to match the name of your add-in. If you have multiple groups, name each group based on the functionality that the commands in that group provide.
- Do not add superfluous buttons to increase the real estate of your add-in.
Add-ins that take up too much space might not pass AppSource validation.
For all icons, follow the icon design guidelines.
Provide a version of your add-in that also works on Office applications that do not support commands. A single add-in manifest can work in both command-aware (with commands) and non-command-aware (as a task pane) applications.
Figure 3. Task pane add-in in Office 2013 and the same add-in using add-in commands in Office 2016
The best way to get started using add-in commands is to take a look at the Office Add-in commands samples on GitHub.