A custom function is identified by an id and name property in the JSON metadata file.
- The function
- The function
nameis used as the display name that appears to a user in Excel.
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.
name can differ from the function
id, such as for localization purposes. In general, a function's
name should stay the same as the
id if there is no compelling reason for them to differ.
id share some common requirements:
idmay only use characters A through Z, numbers zero through nine, underscores, and periods.
namemay use any Unicode alphabetic characters, underscores, and periods.
idmust start with a letter and have a minimum limit of three characters.
Excel uses uppercase letters for built-in function names (such as
SUM). Therefore, consider using uppercase letters for your custom function's
id as a best practice.
name shouldn't be named the same as:
Any cells between A1 to XFD1048576 or any cells between R1C1 to R1048576C16384.
Any Excel 4.0 Macro Function (such as
ECHO). For a full list of these functions, see this Excel Macro Functions Reference document.
If your function
name is the same as a function
name in an add-in that already exists, the #REF! error will appear in your workbook.
To fix a naming conflict, change the
name in your add-in and try the function again. You can also uninstall the add-in with the conflicting name. Or, if you're testing your add-in in different environments, try using a different namespace to differentiate your function (such as
- Consider adding multiple arguments to a function rather than creating multiple functions with the same or similar names.
- Function names should indicate the action of the function, such as
- Avoid ambiguous abbreviations in function names. Clarity is more important than brevity. Choose a name like
- Consistently use the same verbs for functions which perform similar actions. For example, use
=DELETEADDRESS, rather than
- When naming a streaming function, consider adding a note to that effect in the description of the function or adding
STREAMto the end of the function's name.
If you'll be testing your add-in across multiple environments (for example, in development, staging, demo, etc.), we recommend that you maintain a different XML manifest file for each environment. In each manifest file, you can:
- Specify the URLs that correspond to the environment.
- Customize metadata values like
DisplayNameand labels within
Resourcesto indicate the environment, so that end users will be able to identify a sideloaded add-in's corresponding environment.
- Customize the custom functions
namespaceto indicate the environment, if your add-in defines custom functions.
By following this guidance, you'll streamline the testing process and avoid issues that would otherwise occur when an add-in is simultaneously sideloaded for multiple environments.
Localizing function names
You can localize your function names for different languages using separate JSON files and override values in your add-in's manifest file. As a best practice, avoid giving your functions an
name that is a built-in Excel function in another language as this could conflict with localized functions.
For full information on localizing, see Localize custom functions
Learn about error handling best practices.