Build your first OneNote add-in

In this article, you'll walk through the process of building a OneNote add-in by using jQuery and the Office JavaScript API.


Create the add-in project

  1. Use the Yeoman generator to create a OneNote add-in project. Run the following command and then answer the prompts as follows:

    yo office
    • Choose a project type: Office Add-in project using Jquery framework
    • Choose a script type: Javascript
    • What do you want to name your add-in?: My Office Add-in
    • Which Office client application would you like to support?: Onenote

      A screenshot of the prompts and answers for the Yeoman generator

      After you complete the wizard, the generator will create the project and install supporting Node components.

  2. Navigate to the root folder of the project.

    cd "My Office Add-in"

Update the code

  1. In your code editor, open index.html in the root of the project. This file contains the HTML that will be rendered in the add-in's task pane.

  2. Replace the <body> element with the following markup and save the file.

    <body class="ms-font-m ms-welcome">
        <header class="ms-welcome__header ms-bgColor-themeDark ms-u-fadeIn500">
            <h2 class="ms-fontSize-xxl ms-fontWeight-regular ms-fontColor-white">OneNote Add-in</h1>
        <main id="app-body" class="ms-welcome__main">
            <br />
            <p class="ms-font-m">Enter HTML content here:</p>
            <div class="ms-TextField ms-TextField--placeholder">
                <textarea id="textBox" rows="8" cols="30"></textarea>
            <button id="addOutline" class="ms-Button ms-Button--primary">
                <span class="ms-Button-label">Add outline</span>
        <script type="text/javascript" src="node_modules/jquery/dist/jquery.js"></script>
        <script type="text/javascript" src="node_modules/office-ui-fabric-js/dist/js/fabric.js"></script>
  3. Open the file src\index.js to specify the script for the add-in. Replace the entire contents with the following code and save the file.

    import * as OfficeHelpers from "@microsoft/office-js-helpers";
    Office.onReady(() => {
        // Office is ready
        $(document).ready(() => {
            // The document is ready
    async function addOutlineToPage() {
        try {
            await context => {
                var html = "<p>" + $("#textBox").val() + "</p>";
                // Get the current page.
                var page = context.application.getActivePage();
                // Queue a command to load the page with the title property.
                // Add text to the page by using the specified HTML.
                var outline = page.addOutline(40, 90, html);
                // Run the queued commands, and return a promise to indicate task completion.
                return context.sync()
                    .then(function() {
                        console.log("Added outline to page " + page.title);
                    .catch(function(error) {
                        app.showNotification("Error: " + error);
                        console.log("Error: " + error);
                        if (error instanceof OfficeExtension.Error) {
                            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        } catch (error) {
  4. Open the file app.css to specify the custom styles for the add-in. Replace the entire contents with the following and save the file.

    html, body {
        width: 100%;
        height: 100%;
        margin: 0;
        padding: 0;
    ul, p, h1, h2, h3, h4, h5, h6 {
        margin: 0;
        padding: 0;
    .ms-welcome {
        position: relative;
        display: -webkit-flex;
        display: flex;
        -webkit-flex-direction: column;
        flex-direction: column;
        -webkit-flex-wrap: nowrap;
        flex-wrap: nowrap;
        min-height: 500px;
        min-width: 320px;
        overflow: auto;
        overflow-x: hidden;
    .ms-welcome__header {
        min-height: 30px;
        padding: 0px;
        padding-bottom: 5px;
        display: -webkit-flex;
        display: flex;
        -webkit-flex-direction: column;
        flex-direction: column;
        -webkit-flex-wrap: nowrap;
        flex-wrap: nowrap;
        -webkit-align-items: center;
        align-items: center;
        -webkit-justify-content: flex-end;
        justify-content: flex-end;
    .ms-welcome__header > h1 {
        margin-top: 5px;
        text-align: center;
    .ms-welcome__main {
        display: -webkit-flex;
        display: flex;
        -webkit-flex-direction: column;
        flex-direction: column;
        -webkit-flex-wrap: nowrap;
        flex-wrap: nowrap;
        -webkit-align-items: center;
        align-items: left;
        -webkit-flex: 1 0 0;
        flex: 1 0 0;
        padding: 30px 20px;
    .ms-welcome__main > h2 {
        width: 100%;
        text-align: left;
    @media (min-width: 0) and (max-width: 350px) {
        .ms-welcome__features {
            width: 100%;

Update the manifest

  1. Open the file manifest.xml to define the add-in's settings and capabilities.

  2. The ProviderName element has a placeholder value. Replace it with your name.

  3. The DefaultValue attribute of the Description element has a placeholder. Replace it with A task pane add-in for OneNote.

  4. Save the file.

    <ProviderName>John Doe</ProviderName>
    <!-- The display name of your add-in. Used on the store and various places of the Office UI such as the add-ins dialog. -->
    <DisplayName DefaultValue="My Office Add-in" />
    <Description DefaultValue="A task pane add-in for OneNote"/>

Start the dev server

  1. Open a bash terminal in the root of the project ([...]/My Office Add-in) and run the following command to start the dev server.

    npm start
  2. Open either Internet Explorer or Microsoft Edge and navigate to https://localhost:3000. If the page loads without any certificate errors, proceed to the next section in this article (Try it out). If your browser indicates that the site's certificate is not trusted, proceed to the following step.

  3. Office Web Add-ins should use HTTPS, not HTTP, even when you are developing. If your browser indicates that the site's certificate is not trusted, you will need to add the certificate as a trusted certificate. See Adding Self-Signed Certificates as Trusted Root Certificate for details.


    Chrome (web browser) may continue to indicate the the site's certificate is not trusted, even after you have completed the process described in Adding Self-Signed Certificates as Trusted Root Certificate. Therefore, you should use either Internet Explorer or Microsoft Edge to verify that the certificate is trusted.

  4. After your browser loads the add-in page without any certificate errors, you're ready test your add-in.

Try it out

  1. In OneNote Online, open a notebook.

  2. Choose Insert > Office Add-ins to open the Office Add-ins dialog.

    • If you're signed in with your consumer account, select the MY ADD-INS tab, and then choose Upload My Add-in.

    • If you're signed in with your work or school account, select the MY ORGANIZATION tab, and then select Upload My Add-in.

      The following image shows the MY ADD-INS tab for consumer notebooks.

      The Office Add-ins dialog showing the MY ADD-INS tab

  3. In the Upload Add-in dialog, browse to manifest.xml in your project folder, and then choose Upload.

  4. From the Home tab, choose the Show Taskpane button in the ribbon. The add-in task pane opens in an iFrame next to the OneNote page.

  5. Enter the following HTML content in the text area, and then choose Add outline.

    <li>Item #1</li>
    <li>Item #2</li>
    <li>Item #3</li>
    <li>Item #4</li>

    The outline that you specified is added to the page.

    The OneNote add-in built from this walkthrough

Troubleshooting and tips

  • You can debug the add-in using your browser's developer tools. When you're using the Gulp web server and debugging in Internet Explorer or Chrome, you can save your changes locally and then just refresh the add-in's iFrame.

  • When you inspect a OneNote object, the properties that are currently available for use display actual values. Properties that need to be loaded display undefined. Expand the _proto_ node to see properties that are defined on the object but are not yet loaded.

    Unloaded OneNote object in the debugger

  • You need to enable mixed content in the browser if your add-in uses any HTTP resources. Production add-ins should use only secure HTTPS resources.

  • Task pane add-ins can be opened from anywhere, but content add-ins can only be inserted inside regular page content (i.e. not in titles, images, iFrames, etc.).

Next steps

Congratulations, you've successfully created a OneNote add-in! Next, learn more about the core concepts of building OneNote add-ins.

See also