Skip to main content
WordDocument is an OfficeJS-like API. It follows the names and shapes of the Word JavaScript API, so if you know Word.run, you know most of it. It is not OfficeJS-compatible. It is not a drop-in replacement for Office.js, and add-in code does not run on it without changes. There is no Word.run, no request context and no load/sync. Some members are missing, some have a different shape, and some are extensions that Office.js does not have. The differences are below.

Try it

Edit the script. The pages on the right show the result when you stop typing. Click a block on a page to go to the line that made it.

No run, load or sync

Office.js sends a batch of commands to Word and waits. Here the document is in memory, so every property reads at once and every edit applies at once.
There is no load() and no sync(). Remove them when you port add-in code. Values that Office.js wraps in a ClientResult (for example getReviewedText()) have a .value that is ready at once.

Handles and collections

  • A collection (paragraphs, tables, revisions, comments) has .items, .getFirst(), .getFirstOrNullObject() and .length.
  • Collections are live. Read them again after an edit that adds or removes items.
  • A handle points into the document. When its content is removed (for example, a rejected revision), the handle throws no longer part of the document.
  • Re-query ranges after you replace their text or change their container.

Paragraph ids (w14:paraId)

Word gives each paragraph and table row a w14:paraId. Word keeps these ids on save only when every paragraph and row has a valid, unique id. If one id is missing, Word makes new ids for all of them. A file with missing ids:
  • Every paragraph and row gets an id, as Word does when it saves. When a file has no paraIds, or some are missing, the open fills them from the file’s own text and order.
  • Each open of the same file fills the same ids, and every copy in a live session fills them alike. Two different files get different ids.
  • The filled ids go into the next save once you read a uniqueLocalId or make an edit. After that the ids come from the file, so a later text change, by us or by another tool, does not move them.
  • A document whose ids nobody read and that nobody edited saves byte for byte. If you change only its properties (for example a custom property), the body, headers, footers and notes save as they were, with no filled ids.
Edits:
  • Each paragraph and row that you add gets a new id. This applies to the facade, the editor and accepted suggestion cards.
  • An edited paragraph keeps its id.
  • A split follows Word: Enter at the end of a paragraph keeps the id on the first part, and Enter at any other position moves it to the second part.
  • When two paragraphs join, the paragraph whose mark stays keeps its id.
  • insertParagraph keeps the id on the paragraph you call it on. Word gives the id to the new paragraph instead. Both files are valid; only which paragraph holds the id differs.
  • Word keeps all of these ids when it saves the file, and an edit in Word keeps a paragraph’s id.

uniqueLocalId

Paragraph.uniqueLocalId is a GUID built from the paragraph’s paraId. Its first eight digits are the paraId. It stays the same after a save, a reload, a server restart and a round trip through Word. doc.getParagraphByUniqueLocalId(id) finds the paragraph in the body, a header, a footer or a note, and throws ItemNotFound when no paragraph has that id (for example, after you delete it).
  • This goes further than Word. Word makes a new uniqueLocalId for every paragraph each time Word starts, so add-in code written for Word must not expect it to last.
  • The id is unique in one document only. A copy of a file, or a document made from one template, can have the same ids, so key your store by document and id.
  • A split in the middle of a paragraph moves the id to the second part, as described above. The text after the split point keeps the id.
  • Save the document after you read ids from a file that had none. If you do not save, the ids you read are not in the file, and an edit by another tool before the next open can change them.
  • Reading every id costs time in proportion to the number of paragraphs: about 30 ms for 40,000 paragraphs. A lookup by id in the body takes about 1 ms at that size.

Locations

Insert methods take an Office.js location. The values are case-sensitive.

Units

Sizes are in points (72 per inch), as in Office.js. Table, row and column indexes start at 0.

Extensions

Some members do not exist in Office.js but exist in Word’s VBA object model (for example setLineSpacing, documentDefaults, insertMath). They have the VBA name, and the type docs mark them as extensions. Where Office.js has a member, OfficeJS follows its name and behavior.

Layout-backed members

A few members need laid-out pages: readPage(), getRects()-style geometry, updateFields() (page numbers, TOC) and toPdf(). They need a layout host:
  • In Node, @reductoai/docx/node installs one when you import it.
  • In a page, call browserLayoutHost({ fonts }) once. See Office.js in the browser.
  • With @reductoai/docx/officejs alone there is no host. Pure edits work; layout-backed members throw No layout host.

Coverage

OfficeJS covers most of Word.Document, Body, Paragraph, Range, Table, List, ContentControl, Comment, TrackedChange, sections, headers and footers, styles, fields and pictures. The API reference lists every member, and the members that throw because they are not implemented. A value that OfficeJS cannot write throws an error that tells you why; it does not fail silently.