UX design pattern templates for Office Add-ins

The UX design patterns for Office Add-ins project includes HTML, JavaScript, and CSS files that you can use to create the UX for your add-in.

Use the UX design patterns project to:

  • Apply solutions to common customer scenarios.
  • Apply design best practices.
  • Incorporate Office UI Fabric components and styles.
  • Build add-ins that visually integrate with the default Office UI.

Using the UX design patterns

You can use the UX designer specifications as a guide when you create your own UX design, or you can add the source code directly to your project.

To use the specifications to build a mock-up of your own add-in UI:

  1. Download the UX Design Patterns.
  2. Use the Word, Excel, or PowerPoint templates to mock up your extension points for desktop or tablet.
  3. Copy and modify ux design patterns to meet your specific needs.
  4. Refer to templates to browse an Office UI Fabric icon master sheet, view extension points for Word, Excel and PowerPoint (for example, Excel iPad and Excel Windows Desktop), or finalize icons for add-in commands.

To add the source code:

  1. Clone the UX design patterns for Office Add-ins project repo.
  2. Copy the assets folder, and the code folder for the individual pattern you choose to your add-in project.
  3. Incorporate the individual pattern into your add-in. For example:
    • Edit the source location or add-in command URL in the manifest.
    • Use the UX design pattern as a template for other pages.
    • Link to or from the UX design pattern.

Types of UX design patterns

Generic pages

Generic page templates can be applied to any page in your add-in and don't have a special purpose. An example of a special purpose page, would be any of the first-run patterns. The following list describes the generic pages available:

LandingBrand Bar
landing page brand bar

First-Run experience

A first-run experience is the experience a user has when they open your add-in for the first time. The following first-run design pattern templates are available:

The Office Store has a system that manages trial versions of an add-in, but if you want to control the UI of the trial experience for your add-in, use the following patterns:

  • Trial - Shows users how to get started with a trial version of your add-in.
  • Trial feature - Advises users that the feature they are trying to use is not available in the trial version of the add-in. Alternatively, if your add-in is free but it includes a feature that requires a subscription, consider using this pattern. You might also use this pattern to provide a downgraded experience after a trial has ended.

Important: If you decide to manage your own trial, and not use the Office Store to manage the trial, make sure to include the Additional purchase may be required tag in the testing notes in the seller dashboard.

Consider whether showing users the first-run experience once or many times is important to your scenario. For example, if users use your add-in periodically, they might forget how to use it, and it might be helpful to see the first-run experience more than once.

Steps to StartValueVideo
instruction steps value placemat video placemat
Walkthrough first pageTrialTrial feature
walkthrough 1 trial placemat trial placemat feature

Users need to navigate between the different pages of your add-in. The following navigation templates show different options you can use to organize pages and commands in your add-in.

Back buttonNavigationNavigation with commands
back button navigation navigation with commands
PivotTab bar
pivot navigation tab bar

Notifications

Your add-in can notify users of events, such as errors, or of progress in a variety of ways. The following notification templates are available:

  • Embedded dialog box - Shows a dialog box inside the task pane that provides information and, optionally, an interactive experience, using buttons or other controls. Consider using one to prompt a user to confirm an action. Use the Embedded dialog pattern when you want to keep the user experience in the task pane.
  • Inline message - Indicates error, success, or information, and can appear at a specified location in the task pane. For example, if a user enters an incorrectly formatted email address in a text box, an error message appears just below the text box.
  • Message banner - Provides information and, optionally, a simple call to action, in a banner that can be collapsed to a single line, expanded to multiple lines, or dismissed. Use message banners to report a service update or a helpful tip when the add-in starts.
  • Progress bar - Indicates the progress of a long-running, synchronous process, such as a configuration task that must complete before the user can take any further action. It is a separate interstitial page that also reinforces the add-in brand. Use a progress bar when the process can send periodic measures of how far along it is back to the add-in.
  • Spinner - Indicates that a long-running, synchronous process is underway, but provides no indication of how far along it is. It is a separate interstitial page that also reinforces the add-in brand. Use a spinner when the add-in cannot know reliably how far along a process is.
  • Toast - Provides a brief message that fades away after a few seconds. Because the user might not see the message, use toast only for nonessential information. It is a good choice for notifying users of an event in a remote system, such as the receipt of an email.
Embedded dialogInline messageMessage banner
embedded dialog inline message message banner
Progress barSpinnerToast
progress bar spinner toast

General components

The following are general components that you can use in your add-ins in a variety of scenarios.

Client dialog boxes

Client dialog boxes provide another way for users to work with your add-in outside of a task pane. The following dialog box templates are available:

Typeramp dialogAlert dialog
typeramp dialog alert dialog
Navigation dialog
navigation dialog

Feedback and Ratings

To improve the visibility and adoption of your add-in, it is helpful to provide users with the ability to rate and review your add-in in the Office Store. This pattern shows two methods for presenting feedback and ratings from within the add-in:

  • User-initiated feedback - A user chooses to send feedback by using either the navigation menu (for example, using the Send Feedback link) or an icon on the footer.
  • System-initiated feedback - After the add-in runs three times, the user is prompted to provide feedback via a Message Banner.

Either method opens a dialog box that contains the Office Store page for the add-in.

Important: This pattern currently points to the Office Store home page. Be sure to update this URL to the URL of your add-in's page in the Office Store.

Feedback and ratings
Feedback and Ratings

Settings and Privacy

Add-ins may need a Settings page that allows users to configure settings that control the behavior of the add-in. Also, you may want to provide users with the privacy policies your add-in adheres to.

SettingsPrivacy Policy
settings privacy

Additional resources