Edit

Share via

Control element of type Button

  • Article

Defines a button that executes an action or launches a task pane.

Note

This article assumes familiarity with the basic Control reference article which contains important information about the element's attributes.

A button performs a single action when the user selects it. It can either execute a function or show a task pane. Each button control must have an id attribute value that is unique among all <Control> elements in the manifest.

Important

"Button" type controls are ignored on mobile platforms. To support mobile platforms, you must also have a control of type "MobileButton" for every control of type "Button".

Child elements

Element Required Description
Label Yes The text for the button.
Supertip Yes The supertip for the button.

Important: Supertips are only supported in Office desktop clients.
Icon Yes An image for the button.
Action Yes Specifies the action to perform. There can be only one <Action> child of a <Control> element.
Enabled No Specifies whether the control is enabled when the add-in launches.
OverriddenByRibbonApi No Specifies whether the button should appear on application and platform combinations that support custom contextual tabs. If used, it must be the first child element.

Label

Specifies the text for the button by means of its only attribute, resid, which can be no more than 32 characters and must be set to the value of the id attribute of a <String> element in the <ShortStrings> child of the Resources element.

Add-in type: Task pane, Mail

Valid only in these VersionOverrides schemas:

  • Task pane 1.0
  • Mail 1.0
  • Mail 1.1

For more information, see Version overrides in the add-in only manifest.

Associated with these requirement sets:

  • AddinCommands 1.1 when the parent <VersionOverrides> is type Taskpane 1.0.
  • Mailbox 1.3 when the parent <VersionOverrides> is type Mail 1.0.
  • Mailbox 1.5 when the parent <VersionOverrides> is type Mail 1.1.

Examples

In the following example, the button executes a function. It's also configured to be disabled when the add-in launches. It can be programmatically enabled. For more information, see Enable and Disable Add-in Commands.

<Control xsi:type="Button" id="Contoso.msgReadFunctionButton">
  <OverriddenByRibbonApi>true</OverriddenByRibbonApi>
  <Label resid="funcReadButtonLabel" />
  <Supertip>
    <Title resid="funcReadSuperTipTitle" />
    <Description resid="funcReadSuperTipDescription" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="blue-icon-16" />
    <bt:Image size="32" resid="blue-icon-32" />
    <bt:Image size="80" resid="blue-icon-80" />
  </Icon>
  <Action xsi:type="ExecuteFunction">
    <FunctionName>getSubject</FunctionName>
  </Action>
  <Enabled>false</Enabled>
</Control>

In the following example, the button displays a task pane.

<Control xsi:type="Button" id="Contoso.msgReadOpenPaneButton">
  <Label resid="paneReadButtonLabel" />
  <Supertip>
    <Title resid="paneReadSuperTipTitle" />
    <Description resid="paneReadSuperTipDescription" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="green-icon-16" />
    <bt:Image size="32" resid="green-icon-32" />
    <bt:Image size="80" resid="green-icon-80" />
  </Icon>
  <Action xsi:type="ShowTaskpane">
    <SourceLocation resid="readTaskPaneUrl" />
  </Action>
</Control>