Custom functions architecture
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
|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.
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.
storage object can also be useful for authentication. For more information, see Custom functions authentication.
Learn more about how to use the custom functions runtime.