Office.js compatibility
Compare the supported Office.js API subset, known differences, and unavailable APIs.
@docx-editor.dev/editor-api implements a subset of the Office.js object model. Code built on Document, Body, Paragraph, and Range carries over after you replace the host setup and adapt the differences on this page. Compatibility covers the listed subset, not complete Office.js behavior.
Replace the Office.js host
Replace Word.run() with a runtime, and keep the load() and sync() pattern:
import { DocxEditor } from '@docx-editor.dev/editor-api';
const runtime = await DocxEditor.createServer(bytes, { author: 'Migration bot' });
try {
await runtime.run(async (context) => {
const first = context.document.body.search('Total').getFirst();
first.insertText('TOTAL', 'Replace');
await context.sync();
});
} finally {
runtime.dispose();
}The package does not provide Office.onReady or Word.run. In a browser, use DocxEditor.createBrowser(editor) from @docx-editor.dev/editor-api/browser. For host options, see Runtime and setup.
Adapt behavior that differs
| Office.js behavior | DocxEditor behavior | Required change |
|---|---|---|
| The Office.js host supplies the comment author. | No host-provided account identity exists. | Pass { author } when you create the runtime. |
| An item accessor returns a usable proxy at once. | Read-derived proxies resolve prerequisite reads during sync(). A read-derived range can resolve and edit in one sync. | Sync before you inspect loaded values. |
| A load queued after an assignment reads the new value. | A load in the same sync as a write returns the value from before the write. A load on an object that the write returns reports the inserted content. | Load a written property in a later sync. Sync before you edit an inserted object. |
Collections load paths such as items/font/bold. | Collections load items/<property> one level deep. Deeper paths, items/font, and paths on non-collections throw InvalidArgument. | Load navigation objects such as font on each item. |
LoadQueryOptions.expand loads navigation properties. | A nonempty expand throws InvalidArgument. | Load each navigation object directly. |
| A range tracks later edits. | A Range keeps paragraph identities and UTF-16 offsets from when it was found. A text edit before its end makes it fail with StaleDocument. Tracking extends lifetime only. | Search again after an edit, or use the range an insertion returns. |
Paragraph.split() returns ranges and leaves the document unchanged. | Paragraph.split() splits the paragraph and returns the pieces. Each piece keeps its ending delimiter unless trimDelimiters is true. With TrackMineOnly, each new paragraph mark is a tracked insertion, and removing a found delimiter refuses. | Use getTextRanges() to read pieces. Sync before you load the returned pieces. |
sync() can return a pass-through value. | sync() returns Promise<void>. | Keep pass-through values in local state. |
Comment and revision dates are Date. | Invalid or missing file dates return null. | Narrow the nullable Date. |
| Font reads return concrete values. | Mixed, unspecified, or inherited values return null. | Narrow the value before you reuse it in a write. |
ContentControl.id is a number. | ContentControl.id is a string, because DOCX IDs can be missing or repeated. | Do not use it as a unique numeric key. |
ContentControl.subtype uses Office.js interface terms. | subtype uses DOCX terms such as plainText, dropDownList, and checkbox. | Handle the DOCX values. |
Range.select() runs in the Office.js host. | Selection needs an attached browser editor. A server returns NotSupported. | Check runtime.capabilities.selection. |
| Header and footer getters address missing parts. | A getter returns a deferred empty body. Its first write creates the story. | Sync after you resolve the section. |
Office.onReady and Word.run set up the host. | Host creation, capabilities, previews, input budgets, and collaboration are DocxEditor infrastructure. | Treat these as separate from the Office.js-shaped model. |
For proxy lifetime and error recovery, see Batching, loading, and errors.
Check supported APIs
A supported subset covers only the listed operations, not every Office.js member in that area. Each guide owns its refusal rules.
| Area | Status | Key limits | Guide |
|---|---|---|---|
| Batches and lifecycle | Supported subset | No navigation expansion | Batching |
| Paragraphs and ranges | Supported subset | No document-wide start or end offsets | Text and ranges |
| Search | Partial | ignorePunct, ignoreSpace, and matchWildcards set to true fail with NotSupported | Search |
| Bookmarks | Partial | No document-wide offsets | Search |
| Font formatting | Partial | 18 underline styles; 16-color highlight palette | Formatting |
| Paragraph formatting | Supported subset | Values on Paragraph; no full ParagraphFormat object | Formatting |
| Styles | Partial | Read-only definitions; Body, Paragraph, and Range style setters take paragraph styles only; Table.style takes a table style; nameLocal is the styles.xml name | Formatting |
| Lists | Partial | No picture bullets | Lists |
| Tables | Partial | Grid and merge restrictions | Tables |
| Inline pictures | Partial | PNG and JPEG; no floating picture writes | Pictures |
| Fields | Partial | Inert field types only; server evaluation needs measured pagination | Fields |
| Sections and page setup | Partial | Line, Page, and SectionNext breaks only | Page layout |
| Footnotes and endnotes | Supported subset | No note creation | Page layout |
| Shapes and text boxes | Partial | Text stories only; no geometry writes, insertion, or deletion | Page layout |
| Content controls | Partial | No typed subtype objects; bound controls refuse writes | Content controls |
| Comments and replies | Partial | Explicit author; no comment body replacement | Comments |
| Tracked changes | Partial | TrackAll fails; table and wrapper boundaries refuse | Tracked changes |
| Hyperlinks | Partial | Range.hyperlink only | Formatting |
Identify extensions
These members extend the Office.js shape:
| Member | Purpose |
|---|---|
Body.bookmarks, Body.revisions | Enumerate one body story only |
RevisionCollection.resolve(), setAuthor() | Resolve a batch, or change authors, in one story |
Document.footnotes, Document.endnotes, NoteItem.text | Enumerate note parts and read note text |
ContentControlCollection.getByTag(), getByTitle() | Find controls without a file ID |
ContentControl.setValue(), isBound, subtype | Write typed values, preflight bindings (sync checks again), and report DOCX control types |
Comment.text, CommentReply.text | Read comment text |
Paragraph.uniqueLocalId, Paragraph.readingOrder | Paragraph identity for the runtime, and paragraph direction |
getReviewItemRevisions(), getReviewItemRange(), getReviewItemRangeOrNullObject() | Act on a review item key; see Work with review items |
DocxEditorRuntime.preview() | Show edits before you commit them; browser only |
On Range.revisions, acceptAll() and rejectAll() resolve every overlapping change whole, while resolve() and setAuthor() refuse with NotSupported.
Find unavailable APIs
Code that uses these APIs fails TypeScript compilation.
| API | Alternative |
|---|---|
| Picture list levels | Text bullets with an explicit font |
| Shape geometry writes, insertion, deletion, and canvas editing | Shape.body for supported text edits |
| Repeating-section and picture content-control objects | Common ContentControl members |
ContentControl.xmlMapping | ContentControl.isBound; bound writes still fail |
Hyperlink, HyperlinkCollection | Range.hyperlink |
Body.getHtml(), Body.getOoxml(), Paragraph.getText() | Body.text or Paragraph.text; Range.insertOoxml() accepts one equation |
Style.font, Style.paragraphFormat, Style.delete, Document.addStyle, getByName, getItem | StyleCollection.getByNameOrNullObject() |
BookmarkCollection.exists() | Load the collection and inspect its items |
Range.start, Range.end, Bookmark.start, Bookmark.end | Ranges and paragraph text |
Handle typed errors such as NotSupported, NotImplemented, and ItemNotFound for operations outside the subset.
Interpret compatibility reports
CI compares the published declarations with a pinned @types/office-js reference and compiles representative Office.js code against them. The package does not include or fetch the official declarations.
- The broad report covers editing methods and property writes. It excludes reads, navigation, host setup, enums, and support types.
- A separate profile measures 81 document-editing members.
- Signature percentages do not prove runtime equivalence or success on arbitrary documents. Read the per-endpoint runtime notes.
- The shape subset belongs to
WordApiDesktop 1.2and does not extend the 81-member profile.
For report scope and maintenance, see the compatibility report guide.