# What changed in docx

> 86 changes in docx 9 from its official release notes, upgrade guides and advisories: 5 breaking, 43 new APIs and options. Each one cited. Sources checked 2026-10-17. HTML: https://unstale.sh/npm/docx/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## docx 9

### Breaking changes

- Throws when a drawing is too large for Word to open. (9.9.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.9.0)
- Removes the empty WORKAROUND2 export, which was only needed by awesome-typescript-loader. (9.8.1) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.1)
- Removes the empty WORKAROUND3 export, which was only needed by awesome-typescript-loader. (9.8.1) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.1)
- Removes the empty WORKAROUND4 export, which was only needed by awesome-typescript-loader. (9.8.1) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.1)
- External styles are now merged with default styles, affecting generated document styling. (9.5.3) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.5.3)

### New APIs and options

- Can receive note content directly instead of an identifier, adding the note to the document automatically. (9.11.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.11.0)
- Can receive note content directly instead of an identifier, adding the note to the document automatically. (9.11.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.11.0)
- Returns paragraphs and tables from HTML for use in sections and multiple document content locations. (9.11.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.11.0)
- Converts HTML into a paragraph's content for use in paragraphs and paragraph patches. (9.11.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.11.0)
- A paragraph numbering reference can now provide its own definition, which is added when the paragraph is written. (9.11.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.11.0)
- Accepts a numbering option so numbered and bulleted paragraphs in patches work correctly. (9.11.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.11.0)
- Adds document layout calculation matching Word, including page numbers, references, fields, and page contents. (9.9.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.9.0)
- Adds support for footnotes and endnotes in document patching. (9.9.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.9.0)
- Repeats template table rows for each row of supplied data. (9.9.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.9.0)
- Adds footnote and endnote properties to section options. (9.9.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.9.0)
- Adds a locked option to SimpleField. (9.9.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.9.0)
- Converts LaTeX math into editable Word equations, including common commands and environments, and returns components for mixing with hand-built math. (9.8.1) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.1)
- Adds fraction type selection for stacked, skewed, linear or barless fractions. (9.8.1) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.1)
- Adds control over whether integral limits are used. (9.8.1) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.1)
- Adds a component for constructing large mathematical operators used by LaTeX conversion and hand-built equations. (9.8.1) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.1)
- Adds literal handling to MathRun for representing literal mathematical content. (9.8.1) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.1)
- Adds script support to MathRun for constructing scripted mathematical text. (9.8.1) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.1)
- Adds style support to MathRun for controlling the presentation of mathematical text. (9.8.1) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.1)
- Adds control over whether summation limits are used. (9.8.1) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.1)
- Adds new data to charts created and styled in Word while preserving their appearance. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- Adds a chart run that can be inserted where a document placeholder is located. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- Adds native Word charts with many chart types, including combo, radar, bubble, stock, pie-of-pie, and bar-of-pie charts. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- Adds matrices, cases, numbered aligned equations, and brackets made from arbitrary characters while preserving existing math imports. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- Adds preset and custom SVG-path shapes, including diagrams, connectors, canvases, automatic layout, and richer text and fill options. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- Adds text or picture watermarks behind every page, recognized by Word's Design > Watermark menu. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- Images can now be cropped when generating documents. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- ImageRun now supports run properties. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- Adds drawing canvases with connectors and automatic layout for flowcharts, org charts, and swimlane diagrams. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- Adds grouped shapes for composing multiple shapes as a unit. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- Adds runs for inserting shapes into documents. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- Documents now have a theme, configurable through the theme option for colors and fonts used across document elements. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- Generated documents now emit word/commentsIds.xml with durable comment IDs using w16cid. (9.7.2) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.7.2)
- Comments now support replies. (9.7.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.7.0)
- Paragraph indentation now supports firstLineChars. (9.7.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.7.0)
- Numbering levels can now associate with a paragraph style. (9.7.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.7.0)
- Comments now support a resolved state. (9.7.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.7.0)
- Images now support tracked changes in generated documents. (9.7.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.7.0)
- Table look support was added for conditional table formatting. (9.6.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.6.0)
- The docx library now supports creating endnotes. (9.6.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.6.0)
- Track changes support has been extended with additional functionality. (9.6.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.6.0)
- Support was added for WPS text boxes. (9.6.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.6.0)
- Content Controls are now supported, enabling developers to use them in generated DOCX documents. (9.5.2) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.5.2)
- Paragraphs now support between borders, allowing developers to configure this border style. (9.5.2) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.5.2)

### Behavior and default changes

- Bold and italic faces of a font are now embedded in generated documents. (9.10.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.10.0)
- Writes cell widths from columnWidths and applies Word's default cell margins for matching layout. (9.9.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.9.0)
- Can insert ChartRun instances into placeholders and resolve theme colors from a template's own theme. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- Text can use the theme's heading or body font, allowing typography to change when the Word theme changes. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- Table of Contents creation now supports cached data. (9.6.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.6.0)
- Footnotes now support lists and images. (9.6.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.6.0)
- Table of Contents creation has been extended with additional capabilities. (9.6.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.6.0)
- The system now returns which token has not been found, making missing-token errors more actionable. (9.5.3) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.5.3)

### Tooling

- Documentation examples now run with this version, render documents beside editable code, provide completions and type errors, and allow .docx downloads. (9.8.1) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.1)

### Fixes and other changes

- Assigns unique drawing identifiers to inserted images so patched documents remain readable by Word. (9.11.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.11.0)
- Adds or reuses heading styles in templates so patched headings retain their intended formatting. (9.11.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.11.0)
- Writes specVanish from its own option instead of incorrectly deriving it from vanish. (9.11.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.11.0)
- External hyperlink fragments are now preserved in Word documents. (9.10.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.10.0)
- Supports writing a bookmark inside another bookmark. (9.9.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.9.0)
- Preserves embedded fonts when saving a document again. (9.9.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.9.0)
- Writes images and lists contained in endnotes. (9.9.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.9.0)
- Preserves paragraph and character styles supplied through externalStyles. (9.9.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.9.0)
- Makes frame width and height optional. (9.9.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.9.0)
- Calls super() once so ImageRun works under Turbopack. (9.9.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.9.0)
- Packing a document again now writes the same document. (9.9.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.9.0)
- Adds the separate field character to page references. (9.9.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.9.0)
- Inserts an inline bookmark with an identifier unused by the template. (9.9.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.9.0)
- Formats patched link text like its placeholder and adds relationships only where used. (9.9.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.9.0)
- Writes table-of-contents entries from document headings. (9.9.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.9.0)
- Bookmark numeric IDs are now allocated per document. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- A comments part is written only when the document contains comments. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- Style definitions no longer emit an implicit ListParagraph paragraph style. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- Normal is now written as the default paragraph style so Pages draws math at its intended size. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- Repeated document placeholders are now patched in reverse order. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- Theme colors can be used for text, underlines, borders, shading, shapes, and page backgrounds. (9.8.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.8.0)
- Fixed an issue with bundling types, which may affect TypeScript consumers. (9.7.1) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.7.1)
- Embedded fonts now use sequential filenames. (9.7.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.7.0)
- Page size now correctly sets its code. (9.7.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.7.0)
- Passes the characterSet parameter to createRegularFont when generating font tables. (9.6.1) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.6.1)
- First-level numbering now allows zero as the starting number. (9.6.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.6.0)
- Multiple splits within a single run are now handled correctly. (9.6.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.6.0)
- XML is pre-encoded as UTF-8 to prevent surrogate pair corruption in JSZip. (9.6.0) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.6.0)
- Numbered item references are now exported, making that reference available to developers. (9.5.2) — [release notes](https://github.com/dolanmiu/docx/releases/tag/9.5.2)