Get Started with Excel Add-ins

Welcome to the quick start guide for developing Office Add-ins! This tutorial will walk you through creating a simple "Hello World" add-in for Excel. By the end of this guide, you'll have a functional add-in that can be sideloaded into Excel.

Prerequisites

Node.js (LTS version recommended) installed on your machine. Download Node.js
npm (comes with Node.js) or Yarn package manager.
A code editor (like Visual Studio Code).
Office client (Excel) where you can test your add-in. This can be:
- A desktop version of Excel (Windows or Mac).
- Excel for the web.
- Excel on a virtual machine.

Step 1: Set Up Your Development Environment

We'll use the Yeoman generator for Office Add-ins to create our project. This tool scaffolds a basic add-in project with all the necessary files and configurations.

Install the Yeoman Generator

Open your terminal or command prompt and run the following command to install the generator globally:

npm install -g yo generator-office

If you're using Yarn, use:

yarn global add yo generator-office

Step 2: Create Your First Excel Add-in Project

Navigate to the directory where you want to create your project in your terminal and run the generator.

Generate the Project

Run the following command and follow the prompts:

yo office

When prompted:

Choose Excel as the type of project.
Choose Add-in using Angular (or React, or HTML/JS/CSS depending on your preference. For simplicity, we'll assume HTML/JS/CSS here, but the concepts are similar). Let's select Office Add-in project type: Office Add-in project and then choose HTML, CSS, and JavaScript.
Enter a name for your project (e.g., MyExcelAddin).

The generator will create a new folder with your project name and install all the required dependencies. This might take a few minutes.

Step 3: Explore the Project Structure

Navigate into your newly created project directory:

cd MyExcelAddin

Open this folder in your code editor. You'll find a structure like this:


MyExcelAddin/
├── .vscode/
├── images/
├── node_modules/
├── App.js
├── App.html
├── App.css
├── manifest.xml
├── package.json
└── ... (other configuration files)

manifest.xml: This file contains metadata about your add-in, such as its ID, name, description, and permissions.
App.html: The main HTML file for your add-in's user interface.
App.js: The JavaScript file that contains the logic for your add-in.
App.css: The CSS file for styling your add-in.

Step 4: Run Your Add-in

Now, let's start the local development server and see our add-in in action.

Start the Development Server

In your terminal, run:

npm start

Or if you're using Yarn:

yarn start

This command will build your add-in and start a local web server. It will also automatically open your add-in in your default Office client (usually Excel). If it doesn't open automatically, follow the instructions that appear in the terminal.

Important: Your add-in runs in a separate pane within Excel. You'll see a task pane appear on the right side of your Excel window.

Step 5: Interact with Your Add-in

The default "Hello World" add-in usually has a button. Click it and observe how it interacts with Excel.

Understanding the Code

Let's look at a simplified example of the interaction in App.js:


// Office JavaScript API helper functions
(function () {
    Office.onReady(function () {
        $(document).ready(function () {
            $('#run').on('click', insertText);
        });
    });

    function insertText() {
        Office.context.document.setSelectedDataAsync("Hello World from your Excel Add-in!");
    }
})();

This code snippet:

Waits for the Office JavaScript API to be ready.
Attaches a click event handler to a button with the ID run.
When the button is clicked, the insertText function is called.
insertText uses Office.context.document.setSelectedDataAsync to insert text into the currently selected cells in Excel.

Step 6: Customize Your Add-in (Optional)

You can modify App.html, App.css, and App.js to change the look and behavior of your add-in.

Example: Changing the Button Text

Open App.html and find the button element:

<button id="run">Run</button>

Change it to:

<button id="run">Insert Greeting</button>

Save the file. The development server should automatically reload, and you'll see the updated button text in Excel.

Next Steps

Congratulations! You've successfully created and run your first Excel add-in. From here, you can:

Explore more advanced Office.js APIs to interact with worksheets, ranges, charts, and more.
Learn about different add-in commands (like buttons in the ribbon).
Discover how to handle data binding and custom functions.
Read the full documentation on the Microsoft Learn documentation.

View More Tutorials