Custom functions architecture

Custom functions are with their own unique runtime that prioritizes execution of calculations. This article will cover the differences between the custom functions runtime and the browser-based JavaScript engine which powers most other parts of your add-in.

Important

Note that Excel custom functions are available on the following platforms.

  • Office on Windows (version 1904 or later, connected to Office 365 subscription)
  • Office on Mac (version 16.24 or later, connected to Office 365 subscription)
  • Office on the web

Excel custom functions are currently not supported on iPad or in one-time purchase versions of Office 2019 or earlier.

Custom functions runtime

An Office Web Add-in can interact with the user as a task pane, or a content pane, and can include commands and custom functions. All of these parts run in a browser engine runtime except for custom functions. Custom functions run in a separate custom functions runtime to optimize for calculation speed.

Note that if you're using the Yeoman generator for Office Add-ins to generate your project, the custom functions runtime will load through the custom-functions.js script file referenced in the functions.html file. The functions.html serves only to load the runtime and shouldn't be used as the task pane for your add-in.

The following table highlights the differences between the custom functions runtime and the browser engine runtime:

Custom functions runtime Browser engine runtime
Supports returning a value from a cell Supports Office.js APIs and UI elements
Does not have localStorage object, instead uses the OfficeRuntime.storage object. Has localStorage object, can optionally use the OfficeRuntime.storage object.
Does not support interacting with the DOM, or loading libraries that depend on the DOM such as jQuery. Supports interacting with the DOM and loading libraries that depend on the DOM.

Browser engine runtime

The task pane, content add-in, and commands run in a browser engine runtime.

The browser engine runtime supports the Office.js APIs. Keep in mind that any of the Excel APIs, such as APIs which allow you to manipulate Excel tables, run on the browser engine runtime, but aren't directly accessible from the custom functions runtime.

Communicate between runtimes

Your custom functions code cannot directly interact with code in other parts of your web add-in, like the task pane because they are in different runtimes. But in some scenarios you may need to share data, such as passing a token.

The OfficeRuntime.storage object can be used to store data from your custom functions and get data from your task pane code. For more information about storing and sharing data, see Save and share state.

You can see a code sample using the storage object in this Github repository dedicated to patterns and practices. For more general information about the storage object, see Custom functions runtime.

The storage object can also be useful for authentication. For more information, see Custom functions authentication.

Next steps

Learn more about how to use the custom functions runtime.

See also