Best Practices


Provide multiple UI entry points to your add-in by using add-in commands.
Note
Add-in commands are currently supported in Outlook 2016. Other hosts and platforms will support add-in commands in the future.
Add-in command design best practices
Use commands to represent a specific action with a clear and specific outcome for users. Do not combine multiple actions in a single button.
Provide granular actions that make common tasks within your add-in more efficient to perform. Minimize the number of steps an action takes to complete.
Provide meaningful icons and labels for buttons that clearly identify the action the user is taking.
For all icons:
Use PNG format with a transparent background.
Include all eight supported sizes. This creates the best experience for all supported resolutions.
Match the Office visual style. For example:
Keep your shapes simple and avoid multiple colors. Complex graphics are difficult to see at smaller sizes and resolutions.
Don't reuse visual metaphors for dissimilar commands. The same icon used for different actions will cause confusion.
Make your button labels clear and succinct. Use a combination of visual and textual information to convey meaning.
Test your icons in light and dark Office themes and high contrast settings. Note that icons might be difficult to see on dark backgrounds or in high contrast mode.
Use consistent icon sizes and positions to help with visual alignment on the ribbon.
A screenshot that shows add-in command buttons that match the Office style next to buttons that don't match the style
For command surface extension points, such as the ribbon:
Group related actions under a menu control.
Name your group to match the name of your add-in, or the specific functionality that your add-in will provide.
Create a custom tab when no existing tab matches functionality your add-in provides. If you need to display more than six commands, use a custom tab for some or all of the commands.
Note
In Outlook, you can only add groups to the default tab or a custom tab.
Support Office hosts that do and do not support add-in commands. A single add-in with a single manifest file can work in both command-aware and non-command-aware hosts.
A screenshot that shows a task pane add-in in Office 2013 and the same add-in using add-in commands in Office 2016
To design for multiple hosts, in your manifest file, provide the appropriate metadata in:
The top section of the manifest, for non-command-aware hosts.
The VersionOverrides section, for command-aware hosts.
Note
Although a single manifest can target both command-aware and non-command-aware hosts, when you target both types of hosts, you essentially create two different versions of your add-in. You can have the same code (HTML/CSS/JS) for both versions.
To ensure that your add-in works well in both types of hosts:
Modularize your navigation and command components so that you can replace them based to the version of your add-in that is being loaded.
Order your navigation and command elements consistently.
Ensure that navigation and command elements can transition across Office host and task pane UI.
Do not add superfluous buttons to increase the real estate of your add-in.


ribbon button for each top level action
leverage ExecuteAction for actions that don't require UI
use command functions consistent with what they are called in Office where possible
use inline buttons for local actions


NavBar component



© 2019 Better Solutions Limited. All Rights Reserved. © 2019 Better Solutions Limited TopPrev