Skip to content

[WXP] (UI/UX) Create custom KeyTIps article #5579

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
samantharamon wants to merge 8 commits into
base: main
Choose a base branch
from
Draft

[WXP] (UI/UX) Create custom KeyTIps article #5579

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
0f768b8
Draft conceptual article
samantharamon Dec 4, 2025
f04f20a
Apply feedback from review
samantharamon Dec 5, 2025
9dea844
Correct supported tabs and controls
samantharamon Dec 6, 2025
0d36081
Link to reference docs
samantharamon Jan 12, 2026
a697210
Merge branch 'main' into samramon-custom-keytips
samantharamon Jan 16, 2026
7757737
Update information about conflict resolution
samantharamon Feb 25, 2026
a28348e
Add minimum supported versions
samantharamon Mar 13, 2026
ea9dca7
Merge branch 'main' into samramon-custom-keytips
samantharamon Mar 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/design/keyboard-shortcuts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@ Use the following guidelines to create custom key combinations for your add-ins.
- When two characters are linked to the same physical key on a standard keyboard, then they're synonyms in a custom keyboard shortcut. For example, <kbd>Alt</kbd>+<kbd>a</kbd> and <kbd>Alt</kbd>+<kbd>A</kbd> are the same shortcut, as well as <kbd>Ctrl</kbd>+<kbd>-</kbd> and <kbd>Ctrl</kbd>+<kbd>\_</kbd> ("-" and "_" are linked to the same physical key).

> [!NOTE]
> Custom keyboard shortcuts must be pressed simultaneously. KeyTips, also known as sequential key shortcuts (for example, <kbd>Alt</kbd>+<kbd>H</kbd>, <kbd>H</kbd>), aren't supported in Office Add-ins.
> Custom keyboard shortcuts must be pressed simultaneously. For guidance on custom KeyTips, also known as sequential key shortcuts (for example, <kbd>Alt</kbd>+<kbd>H</kbd>, <kbd>H</kbd>), see [Add custom KeyTips to your Office Add-ins](keytips.md).

### Browser shortcuts that can't be overridden

Expand Down
230 changes: 230 additions & 0 deletions docs/design/keytips.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,230 @@
---
title: Custom KeyTips for Office Add-ins
description: Learn how to add custom KeyTips, also known as sequential key shortcuts or access keys, to your Office Add-in.
ms.date: 02/26/2026
ms.topic: how-to
ms.localizationpriority: medium
---

# Add custom KeyTips to your Office Add-ins

KeyTips, also known as sequential key shortcuts or access keys, provide an efficient keyboard navigation method for your add-in's users. Unlike simultaneous keyboard shortcuts (such as Ctrl+S) that are used to run operations within an add-in, KeyTips are pressed in sequence to quickly access options from the Office ribbon. KeyTips help users:

- Quickly navigate the ribbon and access actions more efficiently.
- Support keyboard-only navigation for accessibility.

> [!TIP]
> The keyboard command to access KeyTips varies depending on the platform. To familiarize yourself with KeyTips, see the "Ribbon keyboard shortcuts" section for your platform in the following articles.
>
> - [Excel](https://support.microsoft.com/office/1798d9d5-842a-42b8-9c99-9b7213f0040f)
> - [PowerPoint](https://support.microsoft.com/office/ebb3d20e-dcd4-444f-a38e-bb5c5ed180f4)
> - [Word](https://support.microsoft.com/office/95ef89dd-7142-4b50-afb2-f762f663ceb2)

## Supported Office applications and platforms

Custom KeyTips are supported in the following Office applications and platforms.

| Office app | Office on the web | Office on Windows | Office on Mac |
| ----- | ----- | ----- | ----- |
| Excel | Supported | Supported | Supported |
| Outlook | Not supported | Not supported | Not supported |
| PowerPoint | Supported | Supported | Supported |
| Word | Supported | Supported | Supported |

> [!NOTE]
>
> - For Office on Windows, custom KeyTips require Version 2603 (Build 19822.20000) or later.
> - For Office on Mac, KeyTips require Version 16.107 (Build 26030819) or later.
> - In Office on Mac, KeyTips are turned off by default. Users must turn on KeyTips in their Office settings to use the KeyTips defined for your add-in. For more information, see [Enabling KeyTips in Office for Mac](https://techcommunity.microsoft.com/blog/microsoft365insiderblog/keytips-now-available-in-office-for-mac/4226638).

## Supported surfaces and controls

KeyTips can be defined for the add-in's controls and the ribbon tab in which the add-in appears. The following table outlines which ribbon tabs and controls allow KeyTips for each supported Office application.

| Tab type | Excel | PowerPoint | Word |
| ----- | ----- | ----- | ----- |
| Built-in Office tabs | Supported | Supported | Supported |
| Custom tab | Supported | Supported | Supported |
| Contextual tab | Supported | Not available | Not available |
| Buttons | Supported | Supported | Supported |
| Menu items | Supported | Supported | Supported |

## Configure the manifest

> [!IMPORTANT]
> Custom KeyTips are only supported with the unified manifest for Microsoft 365. If your add-in uses the add-in only manifest, you must migrate to the unified manifest to use KeyTips. For more information, see [Office Add-ins with the unified app manifest for Microsoft 365](../develop/unified-manifest-overview.md).

Custom KeyTips are defined in your add-in's manifest. The following example customizes KeyTips to access the add-in and its actions from the built-in Home tab of Excel, PowerPoint, or Word. Note the following about this markup.

- The `"keytip"` property defines the custom KeyTip. It's specified for the following tabs and controls.
- The Home tab on the ribbon ([`"extensions.ribbons.tabs"`](/microsoft-365/extensibility/schema/extension-ribbons-array-tabs-item?view=m365-app-prev&preserve-view=true) object whose `"builtInTabId"` property is set to `"TabHome"`). For guidance on built-in Office ribbon tabs and their IDs, see [Find the IDs of built-in Office ribbon tabs](../develop/built-in-ui-ids.md).
- The custom contextual tab (`"extensions.ribbons.tabs"` object whose `"id"` property is set to `"CustomTab"`).
- The add-in's button on the ribbon ([`"extensions.ribbons.tabs.groups.controls"`](/microsoft-365/extensibility/schema/extension-common-custom-group-controls-item?view=m365-app-prev&preserve-view=true) object).
- The add-in's menu items on the ribbon ([`"extensions.ribbons.tabs.groups.controls.items"`](/microsoft-365/extensibility/schema/extension-common-custom-control-menu-item?view=m365-app-prev&preserve-view=true)).
- KeyTips support up to three uppercase alphanumeric characters ("A-Z", "0-9").
- KeyTips must be unique across tabs and controls.

```json
{
"extensions": [
{
...
"ribbons": [
{
...
"tabs": [
{
"builtInTabId": "TabHome",
"groups": [
{
"id": "ContosoGroup",
...
"controls": [
{
"id": "AnalyzeButton",
"type": "button",
"label": "Analyze Data",
"icons": [
{
"size": 16,
"url": "https://localhost:3000/assets/icon-16.png"
},
{
"size": 32,
"url": "https://localhost:3000/assets/icon-32.png"
},
{
"size": 80,
"url": "https://localhost:3000/assets/icon-80.png"
}
],
"supertip": {
"title": "Analyze Data",
"description": "Perform advanced data analysis."
},
"actionId": "analyzeData",
"keytip": "AD"
},
{
"id": "DataMenu",
"type": "menu",
...
"items": [
{
"id": "InsertData1",
"type": "menuItem",
"label": "Type 1",
"icons": [
{
"size": 16,
"url": "https://localhost:3000/assets/icon-16.png"
},
{
"size": 32,
"url": "https://localhost:3000/assets/icon-32.png"
},
{
"size": 80,
"url": "https://localhost:3000/assets/icon-80.png"
}
],
"supertip": {
"title": "Insert data type 1",
"description": "Insert data type 1."
},
"actionId": "insertDataType1",
"keytip": "D1"
},
{
"id": "InsertData2",
"type": "menuItem",
"label": "Type 2",
"icons": [
{
"size": 16,
"url": "https://localhost:3000/assets/icon-16.png"
},
{
"size": 32,
"url": "https://localhost:3000/assets/icon-32.png"
},
{
"size": 80,
"url": "https://localhost:3000/assets/icon-80.png"
}
],
"supertip": {
"title": "Insert data type 2",
"description": "Insert data type 2."
},
"actionId": "insertDataType2",
"keytip": "D2"
}
]
}
]
}
],
"keytip": "CH"
},
{
"id": "CustomTab",
"label": "Contoso custom tab",
"groups": [
{
"id": "CustomContosoGroup",
"label": "Contoso Custom Group",
"icons": [
{
"size": 16,
"url": "https://localhost:3000/assets/icon-16.png"
},
{
"size": 32,
"url": "https://localhost:3000/assets/icon-32.png"
},
{
"size": 80,
"url": "https://localhost:3000/assets/icon-80.png"
}
],
"controls": [
{
"id": "CustomTabButton",
...
"keytip": "CTB"
}
]
}
],
"overriddenByRibbonApi": true,
"keytip": "CT"
}
]
}
]
}
]
}
```

## Handle KeyTip conflicts

The Microsoft 365 host application checks for KeyTip conflicts between add-ins and built-in commands. If the host application detects a conflict, it automatically assigns a fallback KeyTip using the <kbd>Y</kbd> prefix followed by a number, such as <kbd>Y1</kbd>, <kbd>Y2</kbd>, or <kbd>Y3</kbd>. These fallback KeyTips ensure that each command remains uniquely accessible by keyboard.

> [!TIP]
> Choose custom KeyTips that are unlikely to overlap with built-in ribbon commands. For a list of built-in KeyTips for each Microsoft 365 host application, see the articles referenced earlier in this article.

## Behavior and limitations

When implementing KeyTips for your add-in, be aware of the following behaviors and limitations.

- Custom KeyTips are only supported in an add-in that uses a unified manifest. If your add-in uses an add-in only manifest, you must convert it to a unified manifest to configure KeyTips. For guidance on converting your manifest, see [Convert an add-in to use the unified manifest for Microsoft 365](../develop/convert-xml-to-json-manifest.md).
- Custom KeyTips support up to three uppercase alphanumeric characters.
- Custom KeyTips won't work in earlier versions of Office applications that don't support KeyTips. In these earlier versions, users will see the default KeyTips assigned to the add-in instead.
- User can't modify the add-in's KeyTips.

## See also

- [Add custom keyboard shortcuts to your Office Add-ins](keyboard-shortcuts.md)
- [Accessibility guidelines for Office Add-ins](accessibility-guidelines.md)