Cross-Platform Office Add-Ins in 2026: One Codebase for Windows, Mac, Web, iOS, and Android

The promise of modern Office extensibility is deceptively simple: write your code once and have it run wherever Office runs. Because the Office Add-ins platform is built on web technologies — HTML, CSS, JavaScript and the Office JavaScript API — a single deployment can, in principle, surface inside Word on a Windows desktop, Excel on a Mac, Outlook in a browser, and Word on an iPad, all from the same set of files on the same server. That is the headline benefit of cross-platform Office add-in development, and for organisations weighing the cost of building and maintaining separate native integrations per platform, it is a compelling one.

The reality is more nuanced. “Write once, run everywhere” is a goal to be engineered towards, not a guarantee you get for free. The hosts (Word, Excel, Outlook, PowerPoint) differ from one another, and each host behaves differently across Windows, Mac, the web, iOS and Android. The underlying webview runtimes differ. Some APIs are unavailable on mobile entirely; others degrade quietly. An add-in that assumes desktop-class capability everywhere will fail in confusing ways on a phone.

This article is a practical architecture guide to building an Office add-in with one codebase that targets Windows, Mac, web and mobile responsibly. We will look at the unified web-based model, the capability differences between platforms, how to design responsive task panes and command surfaces, how to feature-detect and progressively enhance, how to test across the platform matrix, and what AppSource expects from a cross-platform submission.

The unified web-based add-in model

Every Office add-in is, at its core, a web application. Your HTML and JavaScript are loaded into an embedded browser control hosted by the Office client. The add-in communicates with the document through the Office JavaScript API — Office.js — which exposes objects such as Office.context, the host-specific application objects (Word, Excel, Outlook via the mailbox object, PowerPoint), and the common APIs shared across hosts.

Because the execution environment is a webview rather than a native binary, the same JavaScript bundle can be served to a desktop client, a browser tab and a tablet. There is no per-platform compilation step and no separate App Store binary for each operating system. This is precisely what makes a single-codebase strategy viable and is the foundation on which everything below rests.

What you do not get for free is uniform capability. The webview that hosts your code is not the same on every platform:

• On modern Windows, add-ins run inside Microsoft Edge WebView2 (the Chromium-based runtime), provided the WebView2 runtime is installed. Older configurations may fall back to the legacy Internet Explorer-based control, which lacks modern JavaScript and CSS support.
• On Mac and iOS, add-ins run inside WKWebView, Apple’s Safari/WebKit-based control.
• On the web, your add-in runs in whatever browser the user has opened Office in — Edge, Chrome, Safari or Firefox — inside an iframe.
• On Android, add-ins run inside a system WebView based on Chromium.

These runtimes diverge in their JavaScript engine versions, CSS feature support, available storage APIs, and how they handle network requests and certificates. A polyfill or transpilation strategy that assumes evergreen Chromium will break on a legacy IE-based Windows host or behave subtly differently under WKWebView. Treat the runtime as a variable, not a constant.

Why platforms diverge: requirement sets

The mechanism the platform uses to describe what an add-in can do on a given client is the requirement set. A requirement set is a named, versioned grouping of APIs — for example WordApi 1.5, ExcelApi 1.16, or Mailbox 1.13 — that a particular Office client either supports or does not. Each Office client on each platform implements requirement sets up to a certain version. A recent build of Excel on Windows might support ExcelApi 1.17, while Excel on iOS supports an earlier version, and Excel on the web sits somewhere in between depending on the release channel.

This matters because requirement sets are the contract you design against. Rather than asking “what platform am I on?”, the more robust question is “is the capability I need supported here?”. The platform exposes this through Office.context.requirements.isSetSupported():

if (Office.context.requirements.isSetSupported("ExcelApi", "1.16")) {
  // Safe to call APIs introduced in ExcelApi 1.16
} else {
  // Provide a fallback or hide the feature
}

You can also declare a minimum requirement set in the manifest so that the add-in simply does not appear on clients that cannot support its baseline. That is appropriate when the add-in is meaningless below a certain capability level. But for a cross-platform add-in that should run broadly, the better pattern is a low manifest baseline combined with runtime feature detection for the richer capabilities — more on this below.

Capability matrix: what runs where

No two deployments are identical, and the exact support levels move with each Office release, so always confirm against current Microsoft documentation for your target builds. The table below is a representative reference for the broad capability tiers you should plan around in 2026, not a substitute for checking the live requirement-set support pages.

Capability	Windows desktop	Mac desktop	Office on the web	iOS (iPad)	Android
Core task pane (HTML/JS UI)	Yes	Yes	Yes	Yes	Limited / host-dependent
Ribbon (add-in commands)	Yes	Yes	Yes	Limited	Limited
Latest host requirement sets (Word/Excel)	Highest	High	High	Lags desktop	Lags desktop
Shared runtime	Yes	Yes	Yes	No	No
Custom functions (Excel)	Yes	Yes	Yes	No	No
Dialog API (displayDialogAsync)	Yes	Yes	Yes	Yes	Yes
Single sign-on (SSO)	Yes	Yes	Yes	Partial	Partial
Event-based activation (Outlook)	Yes	Yes	Yes	Limited	Limited
WebView2 / Chromium runtime	Yes (with runtime)	WKWebView	Browser engine	WKWebView	System WebView
Local file / OS integration	Constrained	Constrained	Most constrained	Most constrained	Most constrained

The consistent themes are these: mobile lags the desktop on requirement-set versions, the shared runtime and custom functions are desktop-and-web features that are unavailable on iOS and Android, and command surfaces shrink as you move from desktop ribbons to the compact mobile UI. Anything that depends on a feature in the lower rows must be treated as optional and gated behind detection.

Designing the manifest for breadth

The add-in manifest declares your add-in’s identity, permissions, surfaces and requirements. Two formats are relevant in 2026: the long-established XML manifest, and the newer unified manifest (JSON) that aligns Office add-ins with the broader Microsoft 365 app model and supports bundling an add-in alongside other Teams and Microsoft 365 capabilities.

For cross-platform reach, the key consideration is support coverage. The XML manifest remains the most broadly supported format across every host and platform, including mobile. The unified JSON manifest has been maturing rapidly, but its support across the full host-and-platform matrix — particularly on mobile clients — has historically trailed the XML manifest. If your priority is the widest possible reach including iOS and Android today, verify the current unified-manifest support status for your specific hosts before committing; for many cross-platform projects the XML manifest is still the pragmatic baseline, with a migration path to the unified manifest as coverage completes.

Whichever format you choose, design the manifest’s declared requirements conservatively. Declare the minimum requirement set your add-in genuinely needs to function at all, define your add-in commands and task panes, and avoid baking in desktop-only assumptions. Mobile support for Outlook add-ins is declared explicitly in the manifest, and a mobile-capable add-in must provide the appropriately sized icons and a task pane that works within the mobile form factor.

Responsive task panes and command surfaces

A task pane on a 27-inch monitor and a task pane on an iPhone are the same HTML rendered into wildly different viewports. Treat the task pane as a responsive web application from the outset.

Practical guidance:

• Build mobile-first, fluid layouts. Use relative units, CSS flexbox and grid, and media queries to reflow content. A two-column desktop layout should collapse to a single column on narrow screens.
• Prioritise the primary action. On a phone, the user can see only a fraction of what fits on a desktop. The most important control should be reachable without scrolling; secondary controls can move behind progressive disclosure.
• Size touch targets generously. Desktop users have a mouse; mobile users have thumbs. Ensure interactive elements meet accessible minimum target sizes.
• Use the Fluent UI design language so your add-in feels native to Office across platforms, and lean on its responsive components rather than hand-rolling layout behaviour.
• Mind the command surface. Ribbon add-in commands are a desktop and web concept; the mobile UX surfaces add-ins differently and far more sparingly. Do not assume a button you placed on the ribbon is reachable the same way on a tablet. Where command-surface entry points are limited, ensure the task pane itself provides navigation to every feature.

The aim is a single UI that is genuinely usable, not merely renderable, at every size.

Performance on constrained mobile clients

Mobile devices have less memory, less CPU headroom, more variable network conditions, and a webview that is more aggressive about reclaiming resources. An add-in that feels instant on a desktop can feel sluggish or unstable on a phone if you have not budgeted for the difference.

Key measures:

• Minimise and split your bundle. Ship the smallest possible initial payload and lazy-load heavier features on demand. Mobile users on cellular connections pay for every kilobyte in both time and battery.
• Batch your Office.js calls. The promise-and-sync() model in the host-specific APIs is designed for batching. Queue your reads and writes and call context.sync() once rather than repeatedly round-tripping to the document, which is far more expensive on mobile.
• Avoid heavy synchronous work on load. Defer non-essential initialisation. The faster the task pane becomes interactive, the better the perceived performance.
• Cache thoughtfully but expect eviction. The webview may discard state when the add-in is backgrounded. Persist anything important and rehydrate gracefully on reactivation.
• Test on real, mid-range devices. Emulators flatter performance. A three-year-old Android handset is a more honest benchmark than the latest flagship.

The shared runtime

By default, an add-in’s task pane, its command functions and its dialogs can run in separate, short-lived JavaScript runtimes that do not share state. The shared runtime changes this on supported clients by running your add-in’s code in a single, persistent runtime, so that the task pane, ribbon button handlers and other surfaces share one global context and one set of variables. This enables scenarios such as keeping state alive across button clicks, running startup code when the document opens, and coordinating UI between the ribbon and the task pane.

The crucial cross-platform caveat: the shared runtime is available on Windows, Mac and the web, but not on iOS or Android. If your architecture depends on the shared runtime to hold state between interactions, that architecture simply will not function on mobile. Design so that the shared runtime is an enhancement — a way to make the desktop and web experience richer and more cohesive — rather than a load-bearing requirement. On mobile, fall back to passing state explicitly, persisting it to storage, or accepting a more stateless interaction model.

Feature detection and progressive enhancement patterns

The single most important discipline in cross-platform Office add-in development is to detect capabilities at runtime and enhance progressively, rather than branching on platform names or assuming a baseline that does not hold everywhere.

Detect requirement sets, not platforms. As shown earlier, Office.context.requirements.isSetSupported() is your primary tool. Build a small capability layer at start-up that resolves what the current client can do, and have your UI consult that layer:

const capabilities = {
  richExcel: Office.context.requirements.isSetSupported("ExcelApi", "1.16"),
  dialogs: Office.context.requirements.isSetSupported("DialogApi", "1.2"),
  // ...resolve everything the add-in cares about, once.
};

if (capabilities.richExcel) {
  enableAdvancedAnalysisFeature();
} else {
  showBasicAnalysisFeature();
}

Guard at the call site too. Detection at start-up keeps the UI honest, but defensive checks around individual API calls protect against the cases that detection cannot fully predict — and let you catch and handle errors where an operation is unsupported on the current client rather than letting an unhandled exception break the task pane.

Degrade gracefully, do not break. When a capability is absent, prefer hiding or replacing the affected feature over showing a dead button. A user on an iPad should never see a control that throws when tapped; they should see a coherent, if smaller, subset of functionality.

Use the platform value sparingly. Office.context.platform (which reports values such as PC, Mac, OfficeOnline, iOS and Android) and Office.context.diagnostics are legitimately useful for telemetry and for the rare genuinely platform-specific workaround. They are a poor basis for feature decisions, because the same platform can support different requirement-set levels across builds and channels. Detect the capability you need; reach for the platform identifier only when nothing else will do.

Establish a low baseline, layer on top. Set the manifest’s required capability to the minimum the add-in needs to be useful at all, so it appears broadly, then progressively enhance towards the desktop’s full power. This inverts the fragile approach of building for the desktop and patching mobile afterwards.

Testing across the platform matrix

A cross-platform add-in has a genuine test matrix: each host you support, multiplied by Windows, Mac, web, iOS and Android, multiplied by the relevant Office release channels. You cannot rely on testing one configuration and assuming the rest behave.

A pragmatic strategy combines several layers:

• Unit-test your logic in isolation. Keep business logic separate from Office.js calls so it can be tested in an ordinary JavaScript test runner without a host. Mock the Office and host-specific objects at the boundary.
• Automate UI and integration tests in the web host. Office on the web runs in a standard browser, which makes it the most automatable target. Browser automation tools can drive the task pane, exercise flows and run against the actual Office.js loaded in the web client. Use this as your fast, frequent regression gate.
• Sideload and smoke-test on each desktop and mobile client. Sideloading lets you load a development manifest into Word, Excel, Outlook or PowerPoint on each platform. Maintain a documented manual smoke-test script covering the high-risk, platform-divergent paths — shared-runtime behaviour, dialog flows, SSO, and anything gated by feature detection — and run it on Windows, Mac, iPad and an Android device before release.
• Verify your fallbacks deliberately. It is not enough to test the happy path on a capable client. Force the unsupported branches — for instance by checking behaviour on a client that genuinely lacks a requirement set — to confirm that degradation is graceful rather than broken.
• Validate the manifest early. Manifest validation tooling catches structural and policy problems before they reach AppSource, and is cheap to run in CI.

The web host carries the bulk of your automated coverage; the desktop and mobile clients are validated through disciplined sideloaded smoke testing of the paths most likely to diverge.

AppSource distribution for a cross-platform add-in

Publishing to AppSource (Microsoft’s commercial marketplace) subjects your add-in to validation, and a cross-platform submission raises the bar. The validation process checks that your add-in works on the platforms your manifest claims to support. If you declare mobile support, expect it to be tested on mobile; an add-in that errors or shows broken UI on iOS or Android will fail validation.

Practical considerations:

• Only claim what you support. Align the platforms and hosts in your manifest with what you have genuinely tested and made work. Over-claiming is a common cause of rejection.
• Meet the per-platform UI and asset requirements. Provide all required icon sizes, ensure the task pane works within mobile dimensions, and confirm command surfaces behave on each declared platform.
• Ensure graceful behaviour everywhere it appears. Validation favours add-ins that degrade cleanly. Feature detection and sensible fallbacks are not just good engineering — they are what gets a broad submission through review.
• Account for SSO and authentication across platforms. If you use single sign-on, confirm the authentication flow and its fallback work on every platform you target, since SSO support and behaviour vary, particularly on mobile.
• Keep the manifest format in mind. Choose the manifest format whose platform support matches your distribution ambitions, and verify current AppSource support for that format against your target hosts before submission.

A clean, well-tested, conservatively-declared add-in is far more likely to pass first time than one that promises universal reach it cannot deliver.

How McKenna Consultants can help

Building a single Office add-in codebase that runs well across Windows, Mac, the web, iOS and Android is an exercise in disciplined engineering: getting the requirement-set baseline right, designing responsive task panes, architecting around the shared runtime’s limits, building a feature-detection layer that degrades gracefully, and proving it all across a real platform matrix before submitting to AppSource.

As an Office add-in development consultancy in the UK with 22 years of software engineering experience, McKenna Consultants designs, builds and ships cross-platform Office add-ins for Word, Excel, Outlook and PowerPoint. We can help you scope the right capability baseline, architect a maintainable single codebase, set up automated cross-platform testing, and navigate AppSource validation — whether you are starting from scratch or extending an existing add-in to new platforms.

If you are planning a cross-platform Office add-in, or want a review of an add-in that is not behaving consistently across clients, we would be glad to talk. Get in touch with McKenna Consultants to discuss your requirements.