npm / docx
docx
What changed in docx 9, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-17.
5 breaking43 new APIs and options8 behavior and defaults1 tooling29 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initdocx 986 changes
Breaking changes 5
Throws when a drawing is too large for Word to open.
Removes the empty WORKAROUND2 export, which was only needed by awesome-typescript-loader.
Removes the empty WORKAROUND3 export, which was only needed by awesome-typescript-loader.
Removes the empty WORKAROUND4 export, which was only needed by awesome-typescript-loader.
External styles are now merged with default styles, affecting generated document styling.
New APIs and options 43
Can receive note content directly instead of an identifier, adding the note to the document automatically.
Can receive note content directly instead of an identifier, adding the note to the document automatically.
Returns paragraphs and tables from HTML for use in sections and multiple document content locations.
Converts HTML into a paragraph's content for use in paragraphs and paragraph patches.
A paragraph numbering reference can now provide its own definition, which is added when the paragraph is written.
Accepts a numbering option so numbered and bulleted paragraphs in patches work correctly.
Adds document layout calculation matching Word, including page numbers, references, fields, and page contents.
Adds support for footnotes and endnotes in document patching.
Repeats template table rows for each row of supplied data.
Adds footnote and endnote properties to section options.
Adds a locked option to SimpleField.
Converts LaTeX math into editable Word equations, including common commands and environments, and returns components for mixing with hand-built math.
Adds fraction type selection for stacked, skewed, linear or barless fractions.
Adds control over whether integral limits are used.
Adds a component for constructing large mathematical operators used by LaTeX conversion and hand-built equations.
Adds literal handling to MathRun for representing literal mathematical content.
Adds script support to MathRun for constructing scripted mathematical text.
Adds style support to MathRun for controlling the presentation of mathematical text.
Adds control over whether summation limits are used.
Adds new data to charts created and styled in Word while preserving their appearance.
Adds a chart run that can be inserted where a document placeholder is located.
Adds native Word charts with many chart types, including combo, radar, bubble, stock, pie-of-pie, and bar-of-pie charts.
Adds matrices, cases, numbered aligned equations, and brackets made from arbitrary characters while preserving existing math imports.
Adds preset and custom SVG-path shapes, including diagrams, connectors, canvases, automatic layout, and richer text and fill options.
Adds text or picture watermarks behind every page, recognized by Word's Design > Watermark menu.
Images can now be cropped when generating documents.
ImageRun now supports run properties.
Adds drawing canvases with connectors and automatic layout for flowcharts, org charts, and swimlane diagrams.
Adds grouped shapes for composing multiple shapes as a unit.
Adds runs for inserting shapes into documents.
Documents now have a theme, configurable through the theme option for colors and fonts used across document elements.
Generated documents now emit word/commentsIds.xml with durable comment IDs using w16cid.
Comments now support replies.
Paragraph indentation now supports firstLineChars.
Numbering levels can now associate with a paragraph style.
Comments now support a resolved state.
Images now support tracked changes in generated documents.
Table look support was added for conditional table formatting.
The docx library now supports creating endnotes.
Track changes support has been extended with additional functionality.
Support was added for WPS text boxes.
Content Controls are now supported, enabling developers to use them in generated DOCX documents.
Paragraphs now support between borders, allowing developers to configure this border style.
Behavior and default changes 8
Bold and italic faces of a font are now embedded in generated documents.
Writes cell widths from columnWidths and applies Word's default cell margins for matching layout.
Can insert ChartRun instances into placeholders and resolve theme colors from a template's own theme.
Text can use the theme's heading or body font, allowing typography to change when the Word theme changes.
Table of Contents creation now supports cached data.
Footnotes now support lists and images.
Table of Contents creation has been extended with additional capabilities.
The system now returns which token has not been found, making missing-token errors more actionable.
Tooling 1
Documentation examples now run with this version, render documents beside editable code, provide completions and type errors, and allow .docx downloads.
Fixes and other changes 29
Assigns unique drawing identifiers to inserted images so patched documents remain readable by Word.
Adds or reuses heading styles in templates so patched headings retain their intended formatting.
Writes specVanish from its own option instead of incorrectly deriving it from vanish.
External hyperlink fragments are now preserved in Word documents.
Supports writing a bookmark inside another bookmark.
Preserves embedded fonts when saving a document again.
Writes images and lists contained in endnotes.
Preserves paragraph and character styles supplied through externalStyles.
Makes frame width and height optional.
Calls super() once so ImageRun works under Turbopack.
Packing a document again now writes the same document.
Adds the separate field character to page references.
Inserts an inline bookmark with an identifier unused by the template.
Formats patched link text like its placeholder and adds relationships only where used.
Writes table-of-contents entries from document headings.
Bookmark numeric IDs are now allocated per document.
A comments part is written only when the document contains comments.
Style definitions no longer emit an implicit ListParagraph paragraph style.
Normal is now written as the default paragraph style so Pages draws math at its intended size.
Repeated document placeholders are now patched in reverse order.
Theme colors can be used for text, underlines, borders, shading, shapes, and page backgrounds.
Fixed an issue with bundling types, which may affect TypeScript consumers.
Embedded fonts now use sequential filenames.
Page size now correctly sets its code.
Passes the characterSet parameter to createRegularFont when generating font tables.
First-level numbering now allows zero as the starting number.
Multiple splits within a single run are now handled correctly.
XML is pre-encoded as UTF-8 to prevent surrogate pair corruption in JSZip.
Numbered item references are now exported, making that reference available to developers.