How to Convert Word VBA Macro to Office Add-In

You have a Word VBA macro that automates a repetitive task, such as formatting documents or inserting boilerplate text. Distributing this macro to other users is difficult because each person must manually import it into their Normal.dotm template or a document. Office Add-ins provide a modern, secure way to share functionality across Word, Excel, and PowerPoint without requiring users to trust VBA macros. This article explains how to convert your existing VBA macro into an Office Add-in using a task pane and a script file.

Key Takeaways: Converting a VBA Macro to a Task Pane Add-in

Office Add-ins use web technologies (HTML, JavaScript, CSS): Replace VBA code with JavaScript and host the files on a web server or local folder.
Manifest XML defines the add-in identity and capabilities: The manifest tells Word where to find your files and how to display the task pane.
Sideloading is the simplest test method: Use the Word Insert > Add-ins > My Add-ins menu to load an unsigned add-in during development.

What an Office Add-In Is and How It Differs From VBA

An Office Add-in is a web application that runs inside Word, Excel, or PowerPoint. It uses HTML, JavaScript, and CSS instead of VBA. The add-in communicates with the Office application through the Office JavaScript API, which provides access to the document, selection, and settings.

VBA macros run directly in the Word process and have full access to the object model and system resources. Office Add-ins run in a sandboxed browser control. This sandbox prevents the add-in from accessing the local file system or running external executables. The benefit is that users do not need to lower their security settings to enable macros. The add-in can be distributed through AppSource, a network share, or a URL.

Before starting, you need the following:

Word 2019, Word 2021, Word for Microsoft 365, or Word on the web
A text editor such as Notepad or Visual Studio Code
Basic knowledge of JavaScript and HTML
Your VBA macro code as a reference for the logic you want to replicate

Steps to Convert a VBA Macro to an Office Add-In

The conversion involves three main tasks: creating the manifest XML file, writing the HTML and JavaScript files, and sideloading the add-in to test it. The example below converts a simple VBA macro that inserts the current date into the document.

Step 1: Create the Manifest XML File

Create a new folder
Name it DateAddin. This folder will hold all add-in files.

Create a file named manifest.xml
Open a text editor and paste the following XML. Replace https://localhost:3000 with the URL where you host the files or use the local path during testing.

<?xml version="1.0" encoding="UTF-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="TaskPaneApp">
  <Id>c7a8b9d0-1234-5678-9abc-def012345678</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Your Name</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="Insert Date Add-in"/>
  <Description DefaultValue="Inserts the current date at the cursor position."/>
  <Hosts>
    <Host Name="Document"/>
  </Hosts>
  <DefaultSettings>
    <SourceLocation DefaultValue="https://localhost:3000/index.html"/>
  </DefaultSettings>
  <Permissions>ReadWriteDocument</Permissions>
</OfficeApp>

Generate a unique GUID for the Id element
Use an online GUID generator or run [guid]::NewGuid() in PowerShell. Each add-in must have a unique ID.

Step 2: Create the HTML and JavaScript Files

Create index.html
In the same folder, create a file named index.html. Add the following HTML structure:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <title>Insert Date Add-in</title>
  <script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
  <script src="app.js"></script>
</head>
<body>
  <h1>Insert Date</h1>
  <button id="insertDate">Insert Current Date</button>
</body>
</html>

Create app.js
Create a file named app.js in the same folder. Add the following JavaScript. This code replicates a VBA macro that types the current date into the document.

Office.onReady(function(info) {
  if (info.host === Office.HostType.Word) {
    document.getElementById("insertDate").onclick = function() {
      Word.run(function(context) {
        var today = new Date();
        var dateString = today.toLocaleDateString();
        var selection = context.document.getSelection();
        selection.insertText(dateString, Word.InsertLocation.replace);
        return context.sync();
      }).catch(function(error) {
        console.log(error);
      });
    };
  }
});

Check the Office JavaScript API reference for your macro actions
If your VBA macro uses methods like Selection.TypeText or Selection.InsertAfter, search the Office JavaScript API documentation for the equivalent method. The insertText method in the example above replaces selected text.

Step 3: Host the Files and Sideload the Add-In

Host the files on a local web server or a network share
For testing, use a simple HTTP server. With Node.js installed, run npx http-server -p 3000 in the DateAddin folder. The server must use HTTPS for Office Add-ins. Use a self-signed certificate or run the command with the -S flag and a certificate file.
Open Word and go to Insert > Add-ins > My Add-ins
Click Upload My Add-in at the bottom of the dialog.
Browse to your manifest.xml file
Select the file and click Upload. The add-in appears in the task pane.
Test the add-in
Place your cursor in a document and click the Insert Current Date button. The current date should appear.

Common Conversion Issues and How to Fix Them

The Task Pane Shows an Error or Blank Page

This usually means the SourceLocation URL in the manifest is incorrect or the web server is not running. Verify the URL matches the server address exactly, including the port number. If using localhost, ensure the server is active and the certificate is trusted. Open the browser developer tools in the task pane by right-clicking and selecting Inspect to view console errors.

The JavaScript API Method Does Not Work as Expected

The Office JavaScript API does not cover every VBA method. For example, there is no direct equivalent for Dialogs or FileDialog. You must use HTML form controls for user input. Check the Microsoft Office JavaScript API reference for available methods. If a method is missing, you can combine multiple API calls or use Office.context.document properties.

The Add-In Works Only in Word Online but Not in Desktop Word

Desktop Word requires the add-in to be served over HTTPS with a valid certificate. Self-signed certificates work for testing but may require you to add the certificate to the Trusted Root Certification Authorities store on the local machine. For production, use a certificate from a trusted certificate authority.

VBA Macro vs Office Add-In: Key Differences for Developers

Item	VBA Macro	Office Add-In
Programming language	VBA (Visual Basic for Applications)	JavaScript with HTML and CSS
Distribution method	Embedded in document or template	Manifest XML pointing to hosted files
Security model	Depends on macro security settings	Sandboxed, no file system access
Cross-platform support	Windows and Mac (limited)	Windows, Mac, web, iOS, Android
User installation	Manual import or trusted location	One click from Insert > Add-ins
Update mechanism	Replace the macro manually	Update files on the server; users get latest version on next load

Converting a VBA macro to an Office Add-in gives you a modern distribution method that works across platforms without security warnings. Start by replicating the core logic in JavaScript using the Office JavaScript API. After testing with sideloading, you can publish the add-in to your organization’s catalog or to AppSource. For complex macros, consider breaking the functionality into multiple functions and using a task pane with buttons or dropdowns for user interaction.

← Back to WiseChecker Home More in Word Solutions