Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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.
- Support keyboard-only navigation for accessibility.
Tip
The keyboard command to access KeyTips varies depending on the platform. To familiarize yourself with KeyTips, see Use the keyboard to work with the ribbon.
Supported Office applications and platforms
Custom KeyTips are supported in the following Office applications and platforms.
| Office application | 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
Custom KeyTips are supported in Office on Windows and on Mac in specific host versions.
- Windows: Version 2603 (Build 19822.20000) or later
- Mac: Version 16.107 (Build 26030819) or later
To verify the version of the host application, call Office.context.diagnostics.version.
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 |
| Buttons | Supported | Supported | Supported |
| Contextual tab | Not available | Not available | Not available |
| Custom tab | Supported | Supported | Supported |
| Menus | Supported | Supported | Supported |
| Menu items | Not available | Not available | Not available |
Try out a completed add-in
To immediately test custom KeyTips in an Office Add-in, try out the Define KeyTips for the ribbon controls of an Office Add-in sample.
Configure the manifest
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 and a custom tab. Note the following about this markup.
- The
"keytip"property defines the key sequence users press to activate a custom KeyTip. It supports up to three uppercase alphanumeric characters ("A-Z", "0-9"). The"keytip"property is specified for the following tabs and controls.- The Home tab on the ribbon (
"extensions.ribbons.tabs"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. - The custom 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"object whose"type"property is set to"button"). - The add-in's menu control on the ribbon (
"extensions.ribbons.tabs.groups.controls"object whose"type"property is set to"menu").
- The Home tab on the ribbon (
{
"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",
"label": "Manage 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": "Manage Data",
"description": "Options to manage data."
},
"items": [
...
],
"keytip": "MD"
}
]
}
],
"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 Y prefix followed by a number, such as Y1, Y2, or Y3. 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 following articles.
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.
- Custom KeyTips support up to three uppercase alphanumeric characters and must be unique across tabs and controls.
- 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.
- In Office on the web, the X key is reserved and can't be used as a custom KeyTip.
- 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 Use the keyboard to work with the ribbon.
See also
Collaborate with us on GitHub
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
Office Add-ins