Add-in commands for Excel, PowerPoint, and Word

Add-in commands are UI elements that extend the Office UI and start actions in your add-in. You can use add-in commands to add a button on the ribbon or an item to a context menu. When users select an add-in command, they initiate actions such as running JavaScript code, or showing a page of the add-in in a task pane. Add-in commands help users find and use your add-in, which can help increase your add-in's adoption and reuse, and improve customer retention.

For an overview of the feature, see the video Add-in Commands in the Office app ribbon.

Note

SharePoint catalogs do not support add-in commands. You can deploy add-in commands via Centralized Deployment or AppSource, or use sideloading to deploy your add-in command for testing.

Important

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

Screenshot of an add-in command in Excel

Figure 2. Add-in with commands running in Excel on the web

Screenshot of an add-in command in Excel on the web

Command capabilities

The following command capabilities are currently supported.

Note

Content add-ins do not currently support add-in commands.

Extension points

  • Ribbon tabs - Extend built-in tabs or create a new custom tab.
  • Context menus - Extend selected context menus.

Control types

  • Simple buttons - trigger specific actions.
  • Menus - simple menu dropdown with buttons that trigger actions.

Actions

  • ShowTaskpane - Displays one or multiple panes that load custom HTML pages inside them.
  • ExecuteFunction - Loads an invisible HTML page and then execute a JavaScript function within it. To show UI within your function (such as errors, progress, or additional input) you can use the displayDialog API.

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.

Note

This feature is not supported in all Office applications or scenarios. For more information, see Enable and Disable Add-in Commands.

Supported platforms

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

Note

For information about support in Outlook, see Add-in commands for Outlook.

Debugging

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.

Best practices

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.

    Note

    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

    A screenshot that shows a task pane add-in in Office 2013 and the same add-in using add-in commands in Office 2016

Next steps

The best way to get started using add-in commands is to take a look at the Office Add-in commands samples on GitHub.

For more information about specifying add-in commands in your manifest, see Create add-in commands in your manifest and the VersionOverrides reference content.