Naming guidelines

A custom function is identified by an id and name property in the JSON metadata file.

  • The function id is used to uniquely identify custom functions in your JavaScript code.
  • The function name is used as the display name that appears to a user in Excel.

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.

A function 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.

A function's name and id share some common requirements:

  • A function's id may only use characters A through Z, numbers zero through nine, underscores, and periods.

  • A function's name may use any Unicode alphabetic characters, underscores, and periods.

  • Both function name and id must 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 name and id as a best practice.

A function's name shouldn't be named the same as:

Naming conflicts

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 NAMESPACE_NAMEOFFUNCTION).

Best practices

  • 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 =GETZIPCODE instead of ZIPCODE.
  • Avoid ambiguous abbreviations in function names. Clarity is more important than brevity. Choose a name like =INCREASETIME rather than =INC.
  • Consistently use the same verbs for functions which perform similar actions. For example, use =DELETEZIPCODE and =DELETEADDRESS, rather than =DELETEZIPCODE and =REMOVEADDRESS.
  • When naming a streaming function, consider adding a note to that effect in the description of the function or adding STREAM to the end of the function's name.

Tip

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 DisplayName and labels within Resources to indicate the environment, so that end users will be able to identify a sideloaded add-in's corresponding environment.
  • Customize the custom functions namespace to 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 id or 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

Next steps

Learn about error handling best practices.

See also