Office JS – APIs: State of the technology

Since last I wrote about “Web Add-ins” and the Office JavaScript API a lot has happened. Office 2016 with the updated APIs has been released and the APIs are constantly being up-dated. Those with a subscription will receive the updates more regularly than anyone who has installed Office from an msi. Web add-ins for Office 2016 (and later) run not only on the Windows desktop, like VBA, VSTO and other solutions, they also run on Mac, iPad, mobile devices and the on-line versions of the Office applications.

Application-specific APIs, the UI

While the Office JS APIs for Office 2013 stressed common capabilities for all Office applications, those introduced for Office 2016 have been application-specific. Their use in code closely parallels that of the COM object models (that which can be done using VBA or VSTO, for example). Parity has still not been achieved with the COM object models, but much progress has been made. Generally, the APIs provide functionality available on all platforms; parts of the object model that aren’t available universally don’t have priority. (For example, the object model only offers support for Rich Text content controls in Word since those are the only kind available in Word Online.) Most of the work has been done on the Excel side since more (perceived) development is done with Excel than with other Office applications such as Word or PowerPoint.

The progress of the application-specific APIs becomes apparent when you look at the documentation, currently on

Another huge improvement introduced since the original web add-ins is the ability to extend the user interface beyond a taskpane. It’s possible to modify the Ribbon and provide dialog boxes. This is done with the Office UI Fabric.

Documentation, tutorials & support

Unlike previous Office developer documentation, this is sourced on GitHub. You can actually see and download the documentation source, request corrections, make suggestions and ask for clarification.

The Office dev site also provides tutorials and How-to articles. In subsequent blog posts I’ll look at some of these more closely as they use tools VBA developers are usually unacquainted with.

Support for the Office JS APIs is on StackOverflow, in the tag office-js. The Microsoft development team monitors this tag and answers questions about using the APIs.

The Office JS API development team has also provided a useful tool, free of charge, for testing code: Script Lab. It is, itself, a web add-in and runs as a task pane in the Office application. The source code is available on GitHub, as well. This tool is great for testing bits of the object models without needing to load an entire add-in for each little change. It provides IntelliSense as well as some rudimentary debugging capabilities.

In parallel with the tutorials, for getting started I recommend the blog of Office JS API team member David Craig. He’s written a number of articles introducing the technology.

Once you’ve familiarized yourself with the basics and want to understand more, an e-book – Building Office Add-ins – written by one of the Microsoft team (Michael Zlatkovsky) provides background information and more advanced topics.

Future of VBA/COM and migration

“What is the future of VBA?” is still asked quite often. Currently, there are no plans to get rid of VBA (or using the object model via COM). Microsoft recognizes the huge investments that have been made in tools that use the COM object models and that it’s not possible to migrate them. If you read blog posts from the Office JS team you will find such statements.

Should you migrate your solutions or use this technology for new ones? The case for using them is steadily getting stronger, but it depends on what you need. One factor that could affect your decision is the licensing and versioning provided by making your web add-in availble in the Office Store.

If your Office extension should work in environments other than the Windows desktop (or possibly Mac OS) then yes, you should consider the Office JS APIs. Analyze carefully to see whether the APIs cover your requirements. Keep in mind that many things not available in the new APIs are possible in Word by levaraging Word’s ability to read/write Word Open XML to/from documents open in Word.

Important functionatliy that is not possible using either the APIs or Word Open XML:

  • Modifying styles or list templates (new ones can be created)
  • updating field codes

If you need these capabilities then adoption of Office JS needs to wait until they’re added to the object model.

You can influence what gets added, and how quickly, by voting on UserVoice.

Leave a Reply