You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/design/contextual-tabs.md
+6-9Lines changed: 6 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: Create custom contextual tabs in Office Add-ins
3
3
description: Learn how to add custom contextual tabs to your Office Add-in.
4
-
ms.date: 03/26/2025
4
+
ms.date: 06/30/2025
5
5
ms.topic: how-to
6
6
ms.localizationpriority: medium
7
7
---
@@ -72,7 +72,7 @@ The following is an example.
72
72
"tabs": [
73
73
"groups": [
74
74
{
75
-
"id": "contextualTab",
75
+
"id": "ContosoGroup",
76
76
...
77
77
"icons": [
78
78
{
@@ -90,7 +90,7 @@ The following is an example.
90
90
],
91
91
"controls": [
92
92
{
93
-
"id": "contextualButton",
93
+
"id": "WriteDataButton",
94
94
...
95
95
"icons": [
96
96
{
@@ -141,15 +141,15 @@ The following is an example.
141
141
---
142
142
143
143
> [!IMPORTANT]
144
-
> When you move your add-in from development to production, remember to update the URLs in your manifest as needed (such as changing the domain from `localhost` to `contoso.com`).
144
+
> When you move your add-in from development to staging or production, remember to update the URLs in your manifest as needed (such as changing the domain from `localhost` to `contoso.com`).
145
145
146
146
## Define the groups and controls that appear on the tab
147
147
148
148
Unlike custom core tabs, which are defined in the manifest, custom contextual tabs are defined at runtime with a JSON blob. Your code parses the blob into a JavaScript object, and then passes the object to the [Office.ribbon.requestCreateControls](/javascript/api/office/office.ribbon?view=common-js&preserve-view=true#office-office-ribbon-requestcreatecontrols-member(1)) method. Custom contextual tabs are only present in documents on which your add-in is currently running. This is different from custom core tabs which are added to the Office application ribbon when the add-in is installed and remain present when another document is opened. Also, the `requestCreateControls` method may be run only once in a session of your add-in. If it's called again, an error is thrown.
149
149
150
150
We'll construct an example of a contextual tabs JSON blob step-by-step. The full schema for the contextual tab JSON is at [dynamic-ribbon.schema.json](https://developer.microsoft.com/json-schemas/office-js/dynamic-ribbon.schema.json). If you're working in Visual Studio Code, you can use this file to get IntelliSense and to validate your JSON. For more information, see [Editing JSON with Visual Studio Code - JSON schemas and settings](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings).
151
151
152
-
1. Begin by creating a JSON string with two array properties named `actions` and `tabs`. The `actions` array is a specification of all the functions that can be executed by controls on the contextual tab. The `tabs` array defines one or more contextual tabs, *up to a maximum of 20*.
152
+
1. Begin by creating a JSON string with two array properties named `actions` and `tabs`. The `actions` array is a specification of all the functions that can be executed by controls on the contextual tab. The `tabs` array defines one or more contextual tabs.
153
153
154
154
```json
155
155
'{
@@ -181,7 +181,7 @@ We'll construct an example of a contextual tabs JSON blob step-by-step. The full
181
181
182
182
- The `id` property is required. Use a brief, descriptive ID that is unique among all contextual tabs in your add-in.
183
183
- The `label` property is required. It's a user-friendly string to serve as the label of the contextual tab.
184
-
- The `groups` property is required. It defines the groups of controls that will appear on the tab. It must have at least one member *and no more than 20*. (There are also limits on the number of controls that you can have on a custom contextual tab and that will also constrain how many groups that you have. See the next step for more information.)
184
+
- The `groups` property is required. It defines the groups of controls that will appear on the tab. It must have at least one member.
185
185
186
186
> [!NOTE]
187
187
> The tab object can also have an optional `visible` property that specifies whether the tab is visible immediately when the add-in starts up. Since contextual tabs are normally hidden until a user event triggers their visibility (such as the user selecting an entity of some type in the document), the `visible` property defaults to `false` when not present. In a later section, we show how to set the property to `true` in response to an event.
@@ -204,9 +204,6 @@ We'll construct an example of a contextual tabs JSON blob step-by-step. The full
204
204
- The `icon` property's value is an array of objects that specify the icons that the group will have on the ribbon depending on the size of the ribbon and the Office application window.
205
205
- The `controls` property's value is an array of objects that specify the buttons and menus in the group. There must be at least one.
206
206
207
-
> [!IMPORTANT]
208
-
> *The total number of controls on the whole tab can be no more than 20.* For example, you could have 3 groups with 6 controls each, and a fourth group with 2 controls, but you can't have 4 groups with 6 controls each.
0 commit comments