Office JS API: Word Desktop vs Word for Web — Platform Differences, Desktop-Only Features, and SDK Version Guide (August 2026)

Office JS API (also known as Office.js) is Microsoft's official JavaScript library for building cross-platform add-ins that run inside Word, Excel, Outlook, and PowerPoint across Windows, macOS, iPad, and the web browser. When it comes to Word specifically, developers face a critical challenge: not every API that works on Word Desktop is available in Word for the Web, and vice versa. Understanding these platform differences is essential for shipping add-ins that degrade gracefully across all environments.

This blog post — written on August 24, 2026 — provides a definitive comparison of Office JS API support for MS Word Desktop versus MS Word for the Web. We cover which features and APIs are supported only on one platform, how to detect and handle these differences in your code, and a complete breakdown of the WordApi requirement set versions (1.1 through 1.8) and the WordApiDesktop requirement sets (1.1 through 1.5) that define what's available where. If you build Office add-ins for enterprise clients, this guide is your essential reference.

Before comparing platforms, it's important to understand how Office JS works under the hood. Unlike legacy technologies such as COM add-ins or VSTO add-ins (which run native .NET code inside the Office process and are Windows-only), Office JS add-ins are web applications. They render inside an embedded browser control — WebView2 on Windows, WKWebView on macOS/iPad, and the browser's own rendering engine for Word for the Web.

All communication between your add-in and the Word document happens asynchronously through the Office.js API layer. This API layer exposes a rich, promise-based object model (the Word.run() execution context) that lets you read, create, and manipulate paragraphs, ranges, tables, content controls, images, headers, footers, and more.

The Two API Models

Office JS actually contains two distinct API models:

• Common API (Office.*) — The original, shared API surface available across all Office host applications. It provides basic capabilities like reading/writing document content via coercion types (Text, HTML, OOXML), binding to document regions, and handling events. While functional, it's limited in richness.
• Application-Specific API (Word.*) — A far richer, object-model-based API designed specifically for Word. It uses the Word.run() batch execution pattern, provides strongly typed objects (Paragraph, Range, Table, ContentControl, Font, Style, etc.), and supports complex operations like tracked changes, comments, and custom XML. This is the modern API that all new development should target.

The application-specific API is where the platform differences become important, because Microsoft gates feature availability behind requirement sets — versioned collections of related API members. A given version of Word on a given platform may or may not support a particular requirement set.

The WordApi requirement sets are the cross-platform API surface. When a requirement set is designated as a numbered WordApi set (not WordApiDesktop), it means Microsoft has committed to supporting it across all platforms — Word for Windows, macOS, iPad, and the Web. However, roll-out timing may differ, so always verify support at runtime.

Here is a breakdown of every WordApi requirement set released as of August 2026:

Important note: "All platforms" means Microsoft has committed to cross-platform support for the requirement set. In practice, Word for the Web sometimes lags behind Desktop by weeks or months for newer sets (1.7, 1.8). Always use runtime checks rather than assuming availability.

The WordApiDesktop requirement sets contain APIs that Microsoft has deliberately scoped to desktop and mobile platforms only — they are not available in Word for the Web. These sets exist because certain features depend on capabilities that the browser-based Word client cannot provide (file system access, native rendering engine features, COM interop, etc.).

As of August 2026, five WordApiDesktop sets have been published:

A critical architectural decision: when features in WordApiDesktop become stable and feasible on the web platform, Microsoft migrates them into the next cross-platform WordApi set. For example, several comment and tracked-change APIs that started in WordApiDesktop were later promoted to WordApi 1.7. This means the desktop-only boundary is not permanent — it shifts over time as the web platform matures.

Understanding which features are desktop-only is critical for planning your add-in's architecture. Here are the major categories of APIs and features that work on Word Desktop but fail or are unavailable on Word for the Web as of August 2026:

1. Shape and Drawing APIs

The Word.Shape, Word.ShapeCollection, and Word.Canvas objects — introduced in WordApiDesktop 1.2 — allow programmatic creation, manipulation, and formatting of shapes, SmartArt placeholders, and grouped drawing objects. Word for the Web has limited rendering of shapes (they display as images), and the JavaScript API provides no shape manipulation capabilities on the web platform.

2. Document File Operations

Document.open(), Document.close(), and Document.save() with advanced SaveBehavior options (save-as, save-copy) require native file system access that the browser sandbox does not permit. On the web, document saving is handled automatically by the cloud autosave mechanism.

3. Printing

Document.print() from WordApiDesktop 1.4 invokes the operating system's native print dialog. Word for the Web relies on the browser's built-in window.print() functionality, which the add-in can access through standard web APIs but not through Office JS.

4. Advanced Custom XML Part Manipulation

While basic Custom XML parts are available through the Common API on both platforms, the extended manipulation capabilities (complex XPath queries, event-driven binding updates, namespace-aware operations) are more reliable and performant on Desktop. Word for the Web's Custom XML support is functional but limited.

5. Mail Merge Operations

Programmatic mail merge — connecting to data sources, defining merge fields, and executing merge operations — is exclusively a Desktop capability. Word for the Web does not expose mail merge functionality through the API.

6. Macro Execution Bridge

WordApiDesktop 1.5 introduced a bridge allowing Office JS add-ins to invoke VBA macros in the host document. This is inherently desktop-only since VBA does not exist in the web platform.

Beyond outright missing APIs, several features technically work on both platforms but behave differently:

1. Track Changes

The Word UI supports Track Changes on the web, but the JavaScript API's access to tracked change objects is restricted. On Desktop, you can programmatically accept or reject individual changes (WordApi 1.7+). On the Web, you have read access to revision data but limited programmatic accept/reject capabilities, and the behavior may vary depending on the document's co-authoring state.

2. Comments and Annotations

Comment APIs (WordApi 1.4+) are cross-platform, but developers report latency in comment visibility on the web — comments inserted via the API may require a manual refresh or a brief delay before appearing in the UI. Desktop shows them immediately.

3. Performance Characteristics

On Desktop, Word.run() batch operations execute against a native process with direct memory access. On the Web, the same operations require HTTP round-trips to the cloud service, adding latency. Operations that manipulate hundreds of paragraphs or large tables will be noticeably slower on Word for the Web.

4. OOXML Insertion

Range.insertOoxml() works on both platforms, but the rendering fidelity of complex OOXML (nested tables, advanced formatting, embedded objects) is higher on Desktop. The web renderer may simplify or ignore certain OOXML constructs.

5. Content Control Events

Event handlers for content control changes (like onDataChanged and onSelectionChanged) may fire with different timing or frequency on the web versus Desktop. Ensure your event handlers are idempotent to handle potential duplicate firings.

While Word for the Web has fewer APIs than Desktop, it also has unique characteristics developers must account for:

Silent Continuous Updates

Word for the Web is a cloud-hosted service that receives continuous, silent updates. Unlike Desktop (which follows a release cadence tied to Office builds), the web client can gain new API support at any time without version numbering. This is both an advantage (faster access to new features) and a challenge (behavior may change without notice).

Co-Authoring by Default

Word for the Web is inherently multi-user. Your add-in must handle scenarios where multiple users edit simultaneously. Operations that assume single-user access (like bulk document replacement) can produce conflicts. The Word.RequestContext and sync patterns help, but you should design for eventual consistency.

Browser Sandbox Constraints

Add-ins running on the web are subject to standard browser security policies: no file system access, strict CORS enforcement, limited local storage, and third-party cookie restrictions. Any feature requiring local resources (fonts, file dialogs, native clipboard access beyond text/html) will behave differently or fail on the web.

The following table summarizes the key differences between Word Desktop and Word for the Web from an Office JS API development perspective. Use this as a quick reference when planning your cross-platform Office add-in architecture:

Building a single add-in that works across both Word Desktop and Word for the Web requires a disciplined approach to runtime feature detection, graceful degradation, and OOXML fallbacks. Here are the proven patterns used by our Office add-in development team:

1. Runtime Requirement Set Checks (The Foundation)

The most important pattern is the isSetSupported() check. Before calling any API that might be desktop-only, verify that the current host supports the required set:

// Check for WordApiDesktop features before using them
if (Office.context.requirements.isSetSupported('WordApiDesktop', '1.2')) {
  // Safe to use Shape APIs
  await Word.run(async (context) => {
    const shapes = context.document.body.shapes;
    shapes.load('items');
    await context.sync();
    console.log('Found ' + shapes.items.length + ' shapes');
  });
} else {
  // Fallback: inform user or use alternative approach
  console.log('Shape APIs are not available on this platform.');
  showNotification('Shape editing requires the Word desktop app.');
}

// Check for specific WordApi versions
if (Office.context.requirements.isSetSupported('WordApi', '1.7')) {
  // Safe to use tracked change accept/reject
} else if (Office.context.requirements.isSetSupported('WordApi', '1.4')) {
  // Can read comments but not manipulate tracked changes
} else {
  // Fallback to basic Common API operations
}

2. Platform Detection Pattern

For UX decisions (showing/hiding UI elements, displaying platform-specific instructions), detect the host platform:

function getPlatformInfo(): Promise<Office.PlatformType> {
  return new Promise((resolve) => {
    Office.context.diagnostics; // Available in modern Office.js
    const platform = Office.context.platform; 
    // Returns: 'PC', 'Mac', 'iOS', 'Android', or 'OfficeOnline'
    resolve(platform);
  });
}

async function initializeAddIn() {
  const platform = await getPlatformInfo();
  
  if (platform === Office.PlatformType.OfficeOnline) {
    // Hide desktop-only features in the UI
    document.getElementById('shapes-panel')?.classList.add('hidden');
    document.getElementById('print-btn')?.classList.add('hidden');
  }
}

3. Capability-Based Feature Modules

Structure your add-in code into capability modules that self-register based on platform support:

// capabilities/shapes.ts
export function registerShapeCapabilities(app: App) {
  if (!Office.context.requirements.isSetSupported('WordApiDesktop', '1.2')) {
    app.registerFallback('shapes', {
      message: 'Open this document in Word Desktop to use shape tools.',
      action: 'openInDesktop'
    });
    return;
  }
  
  app.registerCapability('shapes', {
    insertShape: async (type, options) => { /* ... */ },
    formatShape: async (shapeId, formatting) => { /* ... */ },
  });
}

// capabilities/comments.ts
export function registerCommentCapabilities(app: App) {
  if (!Office.context.requirements.isSetSupported('WordApi', '1.4')) {
    app.registerFallback('comments', {
      message: 'Update your Office version to use comment features.',
    });
    return;
  }
  
  app.registerCapability('comments', {
    addComment: async (rangeId, text) => { /* ... */ },
    getComments: async () => { /* ... */ },
  });
}

4. OOXML Fallback Strategy

When the native API is unavailable on the web, Office Open XML (OOXML) can often achieve the same result. The insertOoxml() method is cross-platform and lets you insert richly formatted content:

async function insertFormattedContent(context: Word.RequestContext) {
  if (Office.context.requirements.isSetSupported('WordApi', '1.5')) {
    // Use the native API for best results
    const paragraph = context.document.body.insertParagraph(
      'Important Notice', Word.InsertLocation.end
    );
    paragraph.styleBuiltIn = Word.BuiltInStyleName.heading2;
  } else {
    // Fallback to OOXML insertion
    const ooxml = `
      <pkg:package xmlns:pkg="http://schemas.microsoft.com/office/2006/xmlPackage">
        <pkg:part pkg:name="/word/document.xml" 
                 pkg:contentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml">
          <pkg:xmlData>
            <w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
              <w:body>
                <w:p>
                  <w:pPr><w:pStyle w:val="Heading2"/></w:pPr>
                  <w:r><w:t>Important Notice</w:t></w:r>
                </w:p>
              </w:body>
            </w:document>
          </pkg:xmlData>
        </pkg:part>
      </pkg:package>
    `;
    context.document.body.insertOoxml(ooxml, Word.InsertLocation.end);
  }
  await context.sync();
}

5. Manifest Configuration Best Practices

Your add-in manifest can declare minimum requirement sets to ensure the add-in only appears where it can function. However, there's an important limitation: you cannot use WordApiDesktop sets in the classic XML manifest's <Set> element as an activation requirement. This is because doing so would prevent the add-in from loading on the web entirely.

Instead, use the manifest to declare the lowest cross-platform requirement set your add-in needs, and handle desktop-specific features via runtime checks:

<!-- In your manifest.xml -->
<Requirements>
  <Sets DefaultMinVersion="1.4">
    <Set Name="WordApi" MinVersion="1.4" />
  </Sets>
</Requirements>

<!-- Your add-in loads on any platform supporting WordApi 1.4+.
     Desktop-only features are enabled/disabled at runtime. -->

Based on our experience building enterprise Word add-ins at MetaDesign Solutions, we recommend the following layered architecture for managing platform differences:

1. Capability Detection Layer — On add-in startup, run all isSetSupported() checks and build a capabilities manifest object that describes what the current platform supports.
2. Feature Module Layer — Each feature (shapes, comments, tracked changes, printing) is a self-contained module that checks the capabilities manifest before registering its API surface.
3. UI Adaptation Layer — The task pane UI reads the capabilities manifest and conditionally renders buttons, panels, and sections. Desktop-only features are either hidden or shown with a "Desktop only" badge and a helpful message.
4. Fallback Layer — For critical features that must work everywhere, implement OOXML-based fallbacks. For non-critical desktop-only features, provide clear messaging directing users to open the document in the Desktop client.
5. Testing Layer — Maintain test suites that run against both Word Desktop (via Script Lab or sideloading) and Word for the Web (via localhost tunneling). Never assume that passing on Desktop means passing on the Web.

This architecture ensures that your add-in provides the richest possible experience on Desktop while remaining fully functional (with documented limitations) on the Web. For complex enterprise deployments, consider our guide to building custom Office add-ins with Office JS in 2026 for additional architecture patterns.

One of the most common sources of confusion for developers is understanding how Office JS versioning works versus requirement set versioning:

Office JS Library Version vs. Requirement Sets

The Office JS library itself (loaded from https://appsforoffice.microsoft.com/lib/1/hosted/office.js) is a single, always-up-to-date file. Microsoft does not version the CDN library separately — you always get the latest version. The version number in the URL (/lib/1/) is fixed and does not change.

The actual feature gating happens through requirement sets, which are properties of the host application (Word Desktop build 16.0.XXXXX or Word for the Web), not the JavaScript library. This means:

• The Office.js CDN file contains definitions for all requirement sets, including the latest ones.
• Whether a given API actually executes depends on the host application's build number and platform.
• Calling an API from a requirement set not supported by the host will throw a GeneralException or ApiNotFound error.

Backward Compatibility Guarantees

Microsoft maintains strong backward compatibility for Office JS APIs:

• Additive only: New requirement sets only add new APIs — they never remove or break existing ones.
• Superset structure: WordApi 1.5 is a superset of 1.4, which is a superset of 1.3, and so on. If a host supports WordApi 1.5, it supports all APIs from 1.1 through 1.5.
• WordApiDesktop follows the same pattern: WordApiDesktop 1.3 is a superset of 1.2, which is a superset of 1.1.

The NPM Package: @microsoft/office-js

For TypeScript development, you install @microsoft/office-js from npm. This package provides type definitions and is versioned independently (e.g., 1.1.89). The npm version does not correspond to any requirement set — it simply reflects when the type definitions were last updated. Always use the latest npm version for the most complete type definitions.

A critical step that many teams skip: you must test on both platforms. Here is a practical testing checklist:

1. Sideload on Word Desktop — Use the manifest sideloading method or the centralized deployment via Microsoft 365 admin center. Test all features including desktop-only capabilities.
2. Sideload on Word for the Web — Use https://www.office.com, open a document, and sideload your manifest via the "Add-ins" menu. Verify that desktop-only features degrade gracefully (show messages, hide UI).
3. Test the OOXML fallbacks — On Word for the Web, trigger every code path that uses OOXML fallbacks. Verify the rendered output matches expectations.
4. Performance benchmarking — Run performance-critical operations (bulk paragraph insertion, large table creation) on both platforms. Word for the Web may require batching strategies for operations that are instant on Desktop.
5. Co-authoring scenarios — Open the same document in Word for the Web with two users simultaneously while the add-in is active. Verify that add-in operations don't create conflicts or data loss.

For automated testing, consider using Playwright or Puppeteer to drive Word for the Web and validate add-in behavior programmatically. On Desktop, Office's Script Lab tool is invaluable for rapid API experimentation.

To illustrate these patterns, consider a real-world scenario: building a Document Compliance Checker add-in that verifies corporate formatting standards, checks for prohibited content, and applies corrections.

Feature Matrix by Platform

This example shows how a well-architected add-in delivers 80% of its value on both platforms while transparently communicating limitations for the remaining 20%. Our enterprise software solutions team has built dozens of add-ins following this exact pattern for clients in financial services, healthcare, and legal industries.

What is the difference between WordApi and WordApiDesktop requirement sets in Office JS?

WordApi requirement sets (1.1 through 1.8) are cross-platform and supported on Word Desktop, Word for the Web, Word on iPad, and Word on Mac. WordApiDesktop requirement sets (1.1 through 1.5) contain APIs that are exclusively available on Word Desktop (Windows and macOS) and mobile clients — they are not supported in Word for the Web. Use Office.context.requirements.isSetSupported() at runtime to check availability before calling any desktop-specific API.

How do I check if an Office JS API is supported on the current platform at runtime?

Use the Office.context.requirements.isSetSupported(setName, version) method. Pass the requirement set name (e.g., 'WordApi' or 'WordApiDesktop') and the minimum version string (e.g., '1.4'). This returns a boolean indicating whether the current host application supports that requirement set. Always perform this check before calling APIs from newer or desktop-specific requirement sets to avoid runtime exceptions.

Which Office JS APIs work only on Word Desktop and not on Word for the Web?

Key desktop-only APIs include the Shape and Drawing APIs (WordApiDesktop 1.2), Document.open/close/save with SaveBehavior options (WordApiDesktop 1.1), Document.print() (WordApiDesktop 1.4), mail merge operations (WordApiDesktop 1.4), and the VBA macro execution bridge (WordApiDesktop 1.5). Additionally, advanced Custom XML manipulation and certain tracked change operations have limited functionality on the web.

Can I use OOXML as a fallback when an Office JS API is not available on Word for the Web?

Yes, Range.insertOoxml() is supported on both Word Desktop and Word for the Web and is the primary fallback strategy. You can construct Office Open XML packages programmatically to insert richly formatted content — including styled paragraphs, tables, images, and content controls — even when the native JavaScript API for that content type is not available on the web platform. However, be aware that complex OOXML may render with slightly lower fidelity on the web.

How are Office JS SDK versions different from WordApi requirement set versions?

The Office JS SDK (the office.js CDN library and the @microsoft/office-js npm package) is a single, always-current file that contains type definitions for all requirement sets. Its version number (e.g., npm version 1.1.89) reflects when the types were last updated, not which APIs are available. Requirement set versions (e.g., WordApi 1.7) describe the actual API surface supported by a specific build of Word on a specific platform. The SDK version does not determine API availability — the host application's build does.

Building Office add-ins that deliver a seamless experience across Word Desktop and Word for the Web requires deep expertise in platform-specific APIs, graceful degradation patterns, and rigorous cross-platform testing. MetaDesign Solutions has a dedicated Office Add-in Engineering team with years of experience building enterprise-grade Word, Excel, Outlook, and PowerPoint add-ins for Fortune 500 clients.

Explore our Office Add-in Development Services →

Talk to our Office JS experts →