The add-in that only runs in one place
A team wants to extend OneNote so notes flow into their project system, and the obvious answer seems to be a OneNote add-in. Then they discover the catch that derails half these projects: OneNote add-ins run only in OneNote on the web. Not the OneNote desktop app on Windows, not Mac, not the mobile apps. If your users live in desktop OneNote, an add-in will not reach them. OneNote add-in development is genuinely useful inside that boundary, and there is a separate, better path through Microsoft Graph for everything outside it. This guide is the honest version: what a OneNote add-in can do, the web-only limit and why it matters, how the API works, and when to use Graph instead.
Key Takeaways
OneNote add-ins run in OneNote on the web only
This is the constraint that decides most projects. They do not run in the OneNote desktop app, on Mac, or on mobile.
They are web apps using the OneNote JS API
Task pane, content, and command add-ins built on HTML, CSS, and JavaScript, talking to notebooks, sections, and pages through Office.js.
Only the XML manifest is supported
OneNote does not support the unified JSON manifest, so add-ins use the classic add-in-only manifest format.
The API covers page content well
You can read and write page content, add outlines and images, and navigate notebooks, sections, and pages.
Microsoft Graph is the alternative
For automation across notebooks without being inside OneNote, or for reach beyond the web client, the OneNote API in Microsoft Graph is usually the right tool.
Scope is smaller, so cost is lower
Because the surface is constrained, a OneNote add-in is typically a smaller build than an Outlook or Excel add-in.
What is a OneNote add-in?
A OneNote add-in is a web application that extends OneNote on the web through the Office JavaScript API. You can build task pane add-ins, content add-ins, and ribbon commands that read and write page content and connect to web services. OneNote add-ins run only in OneNote on the web and use the classic XML add-in-only manifest.
Structurally a OneNote add-in is like any other Office add-in: a web app of HTML, CSS, and JavaScript hosted on a server, plus a manifest that tells OneNote where the web files live and what UI to add. OneNote loads the add-in in a webview or iframe next to the page. It supports the three add-in types: task pane add-ins that open beside a page, content add-ins that sit inside a page, and add-in commands that extend the ribbon and context menu.
The add-in talks to OneNote through the OneNote JavaScript API, which has an application-specific layer for OneNote objects (Notebook, Section, Page) reached through the Application object, plus a limited slice of the common API for things like reading the current selection. It uses the same proxy-and-sync pattern as the rest of Office.js: you queue operations and call context.sync to run them.
One manifest note up front: OneNote add-ins use the classic XML add-in-only manifest. The newer unified JSON manifest does not support OneNote, so the modern packaging that combines an add-in with a Teams app is not available here.
Why does the web-only limit matter so much?
Because OneNote add-ins run exclusively in OneNote on the web. They do not load in the OneNote desktop app on Windows, on Mac, or on the mobile apps. If your users primarily use desktop OneNote, an add-in cannot reach them, and you need a different approach such as the Microsoft Graph OneNote API.
This is the single most important fact for anyone scoping a OneNote project, and it is the one most likely to be glossed over until it derails the plan. Where Outlook, Excel, Word, and PowerPoint add-ins run across the web and desktop clients, OneNote add-ins run in OneNote on the web and nowhere else.
The practical consequence is a hard qualifying question before you commit: do your users actually work in OneNote on the web? In many organisations the answer is no, people use the desktop OneNote app, and in that case an add-in is a dead end regardless of how good the idea is. It is far cheaper to establish this on day one than after a build.
If your users are web-based, or you can move the relevant workflow to the web client, an add-in is a fine choice within that boundary. If they are not, the honest answer is that the add-in model is the wrong tool, and the right one is Microsoft Graph, covered below. Saying that plainly saves clients real money, which is why we lead with it.
What can a OneNote add-in actually do?
Inside the web-only boundary, the capabilities are solid for content and integration work.
Read and write page content. Set the page title, add outlines, insert text, tables, and images, and read existing content from the page. This is the core of most OneNote add-ins.
Navigate the notebook structure. Work with notebooks, sections, and pages, list them, and move between them, which supports things like templating and content organisation.
Connect to web services. The add-in can call your backend or external APIs, so notes can be enriched, classified, sent to another system, or populated from one. A classic example is a grading or rubric tool that reads student work on a page and writes feedback back to it.
Insert structured content. Drop in pre-built page layouts or templates so users start from a consistent structure rather than a blank page.
The common thread is content on the page plus an external service. OneNote add-ins are at their best as a bridge between a OneNote page and a web system, not as deep automation across an entire notebook estate, which is where Graph takes over.
await OneNote.run(async (context) => {
const page = context.application.getActivePage();
page.title = "Project Notes";
const html = "<p><ol><li>Summary</li><li>Action items</li></ol></p>";
page.addOutline(40, 90, html); // x, y, HTML content
await context.sync();
});When should I use Microsoft Graph instead of a OneNote add-in?
Use the Microsoft Graph OneNote API when you need to work with notebooks, sections, and pages from outside OneNote, such as a server-side process, a scheduled job, or another application, or when you need reach beyond the web client. Graph operates on OneNote content across the tenant without requiring the user to be inside OneNote on the web.
Microsoft Graph exposes a OneNote API that works on the same notebook, section, and page hierarchy, but from the outside. Your application calls Graph with the right permissions and reads or writes OneNote content directly, with no add-in and no requirement that anyone has OneNote open at all.
This is the right tool for a large set of real needs that the add-in model cannot serve. A nightly job that files meeting notes into the correct notebook. A web application that creates a structured page when a project is created. A reporting process that pulls content out of many notebooks. A workflow triggered from Power Automate. None of these depend on OneNote on the web, and all of them are natural fits for Graph.
The decision is simple once you frame it. If the experience needs to live inside OneNote on the web as the user works, build an add-in. If the work happens around OneNote, on a server, on a schedule, or from another app, use Graph. A surprising number of projects that start as add-in requests are really Graph projects in disguise, and recognising that early is the most valuable thing an experienced developer brings to a OneNote brief.
OneNote is the one Office app where the wrong approach is easy to pick, because the add-in model looks right and quietly is not for desktop users. The cheapest first step is a short assessment of where your users work and what the workflow actually needs, which usually settles the add-in-versus-Graph question fast. See how we approach it on our page.Office Add-in development services
What does a OneNote add-in cost, and how do you ship it?
Because the surface is constrained, a OneNote add-in is often a smaller build than other Office add-ins, commonly a few thousand dollars over a couple of weeks for a focused content-and-integration tool. A Graph-based solution is priced like any backend integration, scaled to the systems involved.
A OneNote add-in that reads a page, calls a service, and writes content back is a modest project. Cost rises with the depth of the external integration and any AI features, as it does for every add-in, but the OneNote-specific scope is usually narrower than an Outlook or Excel build.
For distribution, an internal add-in deploys through the Microsoft 365 admin center to chosen users or groups, with no review. A public add-in goes through AppSource, where the same rules apply across all Office add-ins: HTTPS only, no localhost, valid live support, privacy, and license URLs, and validation that the add-in works on the platforms its APIs support. Our AppSource publishing guide covers the full checklist. A Graph-based solution is not an add-in at all, so it is deployed like any web application or service you host, with the appropriate Graph permissions consented in Entra ID.
OneNote add-in vs Microsoft Graph OneNote API
| Factor | OneNote add-in | Microsoft Graph OneNote API |
|---|---|---|
| Runs inside OneNote UI | Yes (web only) | No (external) |
| Reaches desktop / Mac / mobile OneNote | No | Yes (content level) |
| Works without OneNote open | No | Yes |
| Best for | In-app experience as user works | Automation, server jobs, other apps |
| Triggered by Power Automate | No | Yes |
| Manifest / packaging | XML add-in-only manifest | N/A (web app + Graph permissions) |
Frequently asked questions
Do OneNote add-ins work in the desktop OneNote app?
No. OneNote add-ins run only in OneNote on the web. They do not load in the OneNote desktop app on Windows, on Mac, or on the mobile apps. If your users work in desktop OneNote, you need a different approach, usually the Microsoft Graph OneNote API.
What can a OneNote add-in do?
Within OneNote on the web, it can set page titles, add outlines, insert text, tables, and images, read existing content, navigate notebooks and sections, and call external web services. A common use is a tool that reads a page and writes results back, such as a grading aid.
Does OneNote support the unified manifest?
No. OneNote add-ins use the classic XML add-in-only manifest. The unified JSON manifest does not support OneNote, so you cannot combine a OneNote add-in with a Teams app into a single Microsoft 365 package the way you can for Outlook.
When should I use Microsoft Graph instead of an add-in?
Use Graph when the work happens outside OneNote: a server job, a scheduled task, a Power Automate flow, or another application that needs to read or write notebook content. Graph operates on OneNote content without requiring the user to be inside OneNote on the web.
Can a OneNote add-in use AI to summarise or organise notes?
Yes, within the web client. The add-in reads the page content, sends it to a backend that brokers the AI model, and writes the result back to the page. For AI processing across many notebooks unattended, a Graph-based service is the better design.
Is OneNote add-in development worth it?
It is, when your users work in OneNote on the web and you need an in-app experience. When they use desktop OneNote or you need automation around OneNote, Microsoft Graph is the better and often cheaper tool. The key is choosing the right one before building.
Right tool first, then build
OneNote add-in development is useful, but it is hemmed in by one fact that decides most projects: add-ins run only in OneNote on the web. Get that question answered first. If your users are web-based and you want an experience inside OneNote as they work, an add-in is a clean, modest build. If they use desktop OneNote, or the work happens around OneNote rather than inside it, the Microsoft Graph OneNote API is the honest answer and usually the better one. We would rather tell you that on day one than after a sprint. If you have a OneNote workflow you want to improve, tell us where your users work and what it needs to do, and we will point you at the right path. Reach out through our contact page anytime.