Support older Microsoft browsers and Office versions

Important

Internet Explorer and Microsoft Edge Legacy are still used in Office Add-ins

Some combinations of platforms and Office versions, including perpetual versions through Office 2019, still use the webview controls that come with Internet Explorer 11 and Microsoft Edge Legacy (EdgeHTML-based) to host add-ins, as explained in Browsers used by Office Add-ins. We recommend (but don't require) that you support these combinations, at least in a minimal way, by providing users of your add-in a graceful failure message when your add-in is launched in these webviews. Keep these additional points in mind:

  • Office on the web no longer opens in Internet Explorer or Microsoft Edge Legacy. Consequently, AppSource doesn't test add-ins in Office on the web on these browsers.
  • AppSource still tests for combinations of platform and Office desktop versions that use Internet Explorer and Microsoft Edge Legacy. However, it only issues a warning when the add-in doesn't support these browsers. The add-in isn't rejected by AppSource.
  • The Script Lab tool no longer supports Internet Explorer.

Office Add-ins are web applications that are displayed inside IFrames when running on Office on the web. Office Add-ins are displayed using embedded browser controls when running in Office on Windows or Office on the Mac. The embedded browser controls are supplied by the operating system or by a browser installed on the user's computer.

If you plan to support older versions of Windows and Office, your add-in must work in the embeddable browser controls used by these versions. For example, browser controls based on Internet Explorer 11 (IE11) or Microsoft Edge Legacy (EdgeHTML-based). For information about which combinations of Windows and Office use these browser controls, see Browsers used by Office Add-ins.

Determine the browser the add-in is running in at runtime

Your add-in can discover the browser it's running in by reading the window.navigator.userAgent property. This enables the add-in to either provide an alternate experience or gracefully fail. The following is an example that determines whether the add-in is running in IE11 or Microsoft Edge Legacy.

if (navigator.userAgent.indexOf("Trident") !== -1) {
    /*
       IE11 is the browser in use. Do one of the following:
        1. Provide an alternate add-in experience that doesn't use any of the HTML5
           features that aren't supported in IE11.
        2. Enable the add-in to gracefully fail by adding a message to the UI that
           says something similar to:
           "This add-in won't run in your version of Office. Please upgrade either to
           perpetual Office 2021 or to a Microsoft 365 account."
    */
} else if (navigator.userAgent.indexOf("Edge") !== -1) {
    /*
       Microsoft Edge Legacy is the browser in use. Do one of the following:
        1. Provide an alternate add-in experience that's supported in Microsoft Edge Legacy.
        2. Enable the add-in to gracefully fail by adding a message to the UI that
           says something similar to:
           "This add-in won't run in your version of Office. Please upgrade either to
           perpetual Office 2021 or to a Microsoft 365 account."
    */
} else {
    /* 
       Another browser, other than IE11 or Microsoft Edge Legacy, is in use.
       Provide a full-featured version of the add-in here.
    */
}

Important

It's not usually a good practice to read the userAgent property. Be sure you're familiar with the article, Browser detection using the user agent, including the recommendations and alternatives to reading userAgent. In particular, if you're providing an alternate add-in experience to support the use of Internet Explorer 11, consider using feature detection instead of testing for the user agent.

As of September 30th, 2021, the text in the section Which part of the user agent contains the information you are looking for? dates from before Internet Explorer 11 was released. It's still generally accurate and the tables in the section of the English version of the article are up-to-date. Similarly, the text, and in most cases the tables, in the non-English versions of the article are out-of-date.

Review browser and Office version support information

For more information on how to support specific browsers and Office versions, select the applicable tab.

Important

Internet Explorer 11 doesn't support some HTML5 features such as media, recording, and location. If your add-in must support Internet Explorer 11, then you must either design the add-in to avoid these unsupported features or the add-in must detect when Internet Explorer is being used and provide an alternate experience that doesn't use the unsupported features. For more information, see Determine the browser the add-in is running in at runtime.

Support for recent versions of JavaScript

Internet Explorer 11 doesn't support JavaScript versions later than ES5. If you want to use the syntax and features of ECMAScript 2015 or later, or TypeScript, you have two options as described in this article. You can also combine these two techniques.

Use a transpiler

You can write your code in either TypeScript or modern JavaScript and then transpile it at build-time into ES5 JavaScript. The resulting ES5 files are what you upload to your add-in's web application.

There are two popular transpilers. Both of them can work with source files that are TypeScript or post-ES5 JavaScript. They also work with React files (.jsx and .tsx).

See the documentation for either of them for information about installing and configuring the transpiler in your add-in project. We recommend that you use a task runner, such as Grunt or WebPack to automate the transpilation. For a sample add-in that uses tsc, see Office Add-in Microsoft Graph React. For a sample that uses babel, see Offline Storage Add-in.

Note

If you're using Visual Studio (not Visual Studio Code), tsc is probably easiest to use. You can install support for it with a nuget package. For more information, see JavaScript and TypeScript in Visual Studio 2019. To use babel with Visual Studio, create a build script or use the Task Runner Explorer in Visual Studio with tools like the WebPack Task Runner or NPM Task Runner.

Use a polyfill

A polyfill is earlier-version JavaScript that duplicates functionality from more recent versions of JavaScript. The polyfill works in browsers that don't support the later JavaScript versions. For example, the string method startsWith wasn't part of the ES5 version of JavaScript, and so it won't run in Internet Explorer 11. There are polyfill libraries, written in ES5, that define and implement a startsWith method. We recommend the core-js polyfill library.

To use a polyfill library, load it like any other JavaScript file or module. For example, you can use a <script> tag in the add-in's home page HTML file (for example <script src="/js/core-js.js"></script>), or you can use an import statement in a JavaScript file (for example, import 'core-js';). When the JavaScript engine sees a method like startsWith, it will first look to see if there's a method of that name built into the language. If there is, it will call the native method. If, and only if, the method isn't built-in, the engine will look in all loaded files for it. So, the polyfilled version isn't used in browsers that support the native version.

Importing the entire core-js library will import all core-js features. You can also import only the polyfills that your Office Add-in requires. For instructions about how to do this, see CommonJS APIs. The core-js library has most of the polyfills that you need. There are a few exceptions detailed in the Missing Polyfills section of the core-js documentation. For example, it doesn't support fetch, but you can use the fetch polyfill.

For a sample add-in that uses core.js, see Word Add-in Angular2 StyleChecker.

Test an add-in on Internet Explorer

See Internet Explorer 11 testing.

See also