Define custom actions to modify the ribbon
Updated: November 29, 2016
Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
The default, an application command bar or ribbon is defined by Microsoft Dynamics 365 metadata. This default data can’t be changed, but you can include definitions of specific actions that will override the default ribbon.
There are two types of custom actions for ribbons:
<CustomAction> (RibbonDiffXml): Defines an action to add or replace items in the ribbon.
<HideCustomAction> (RibbonDiffXml) : Removes an existing ribbon element from being processed for the ribbon.
A custom action is a statement of how you want to change the default ribbon definition. It is evaluated and applied to the ribbon at runtime. To set the context for a custom action, you must include information about the location of the items that you want to change. Use the Location attribute to specify where your change applies.
When you add a new ribbon element, you refer to the containing element, for example, an existing tab or group. You then include the suffix ._children to indicate that this custom action will add something to an existing item.
When you change the definition of an existing item, the Location value will match the ID of that item.
You must also specify a unique identifier for the custom action. Use the Id attribute to set this value. We strongly recommend that you use a naming convention that will guarantee a unique value. For consistency and readability, we recommend that you use a period to separate consistent components. The first item in your naming convention should be something related to your solutions publisher or solution, for example, Contoso.contact.form.CustomButton.CustomAction.
Tip |
|---|
Consistently applying your Id attribute naming conventions will greatly enhance your productivity while editing RibbonDiffXml. |
Based on the location information that you provide, the Sequence attribute value determines the order in which to render items. If you want a custom control to appear between two existing controls, you must select a sequence value that is in between the sequence values of the existing items.
A <HideCustomAction> (RibbonDiffXml) is a statement that you use when you want to remove an existing ribbon element so that it is not rendered. This does not hide the ribbon element, it actually removes the ribbon element at runtime so that it doesn’t exist in the ribbon.
Note |
|---|
Because the HideCustomAction element removes a specified node from the ribbon, removing ribbon elements in this manner may not be the best option for every situation.
|
The HideActionId element provides a unique ID for the action. For consistency and readability, you should follow the same naming convention described for <CustomAction> elements. The Location attribute must match the Id of the ribbon element you want to remove.
Microsoft Dynamics 365
© 2016 Microsoft. All rights reserved. Copyright

