9.8.0

9.8.0 is one of the biggest releases of docx yet. It adds charts, shapes and watermarks, and a lot more math. Each has its own entry point (docx/charts, docx/shapes, docx/watermarks and docx/math), so your bundle only includes the ones you import.

Charts are native Word charts, not pictures. Word draws them from their data in the document's theme, and Edit Data opens that data in Excel. You can make column, bar, line, area, pie, doughnut, pie of pie, bar of pie, radar, scatter, bubble, stock and combo charts, with trendlines, error bars, categories in groups and more. Charts also work in templates. patchDocument can put a new ChartRun where a placeholder is, and ChartDataPatch gives new data to a chart made and styled in Word while keeping its look.

Shapes cover Word's preset shapes (rectangles, ellipses, arrows, callouts, flowchart symbols and the rest), plus custom shapes drawn from SVG paths. You can group shapes with ShapeGroupRun, or join them with connectors on a ShapeCanvasRun and let automatic layout place them, which is how you'd build flowcharts, org charts and swimlane diagrams. Math gains matrices, cases, equations lined up with numbers, and brackets made of any characters. Math you already import from docx keeps working there. Watermarks are text or pictures behind every page, and Word recognises them in its own Design > Watermark menu.

Every document now has a theme, and you can set its colours and fonts with the theme option. Text, underlines, borders, shading, shapes and the page background can use theme colours, and text can use the theme's heading or body font, so they all change when the theme is changed in Word. patchDocument works out theme colours from the template's own theme.

Every demo's document is now checked with the Open XML SDK validator in CI, and this release fixes everything it found. Thank you to everyone who contributed, and welcome to our five new contributors: @slmnsh added image cropping, @theunal watermarks, @holm run properties on ImageRun, and @omartuhintvs and @fushanbobfan fixes to tables and the patcher.

What's Changed

• Add support for cropping images by @slmnsh in #3505
• fix: allocate bookmark numeric ids per document by @alexvcasillas in #3502
• fix(table): emit numeric pct widths in fiftieths of a percent by @omartuhintvs in #3476
• docs: fix "Get Started" cover link and GitHub corner overlap by @dolanmiu in #3518
• fix(styles): stop emitting an implicit ListParagraph pStyle inside style definitions by @dolanmiu in #3519
• fix: Inquirer list deprecation by @dolanmiu in #3520
• feat: Watermarks by @theunal in #3221
• feat: add shapes with ShapeRun and ShapeGroupRun by @dolanmiu in #3521
• feat(shapes): readable names, connectors and drawing canvases by @dolanmiu in #3522
• feat(shapes): effects, pattern and picture fills, text layout, custom shapes and richer diagrams by @dolanmiu in #3523
• feat(shapes): automatic layout, text sizing, connector polish and visual regression tests by @dolanmiu in #3533
• feat: shapes in docx/shapes and watermarks in docx/watermarks by @dolanmiu in #3534
• feat(shapes): text in document styles, swimlanes, routing, descriptions, percentages and text flows by @dolanmiu in #3535
• feat: write a theme part, with theme fonts for text and theme colours for shapes by @dolanmiu in #3536
• feat: theme colours for text, underlines, borders and shading by @dolanmiu in #3537
• feat: theme colours for the page background, and templates' themes in patchDocument by @dolanmiu in #3538
• fix(patcher): patch repeated document placeholders in reverse order by @fushanbobfan in #3540
• feat(shapes): custom shapes with several paths, holes, text areas and connection points by @dolanmiu in #3539
• fix(textbox): write a text box's picture in a run, and only that run inside a paragraph by @dolanmiu in #3541
• ci: run the demos in parallel by @dolanmiu in #3542
• build(deps-dev): bump vite-plugin-dts from 5.0.3 to 5.1.1 by @dependabot[bot] in #3525
• build(deps-dev): bump execa from 9.6.1 to 10.0.1 by @dependabot[bot] in #3524
• build(deps-dev): bump vite from 8.0.16 to 8.3.0 by @dependabot[bot] in #3529
• build(deps): bump @types/node from 25.9.1 to 26.6.2 by @dependabot[bot] in #3530
• build(deps-dev): bump @vitest/ui from 4.1.7 to 5.0.1 by @dependabot[bot] in #3531
• build(deps-dev): bump jsdom from 29.1.1 to 30.1.0 by @dependabot[bot] in #3532
• build(deps): bump jszip from 3.10.1 to 3.10.2 by @dependabot[bot] in #3528
• build(deps-dev): bump eslint-plugin-jsdoc from 63.0.0 to 64.5.4 by @dependabot[bot] in #3527
• fix: make every demo's document valid, and check them all with the Open XML SDK validator by @dolanmiu in #3543
• build(deps-dev): bump eslint-plugin-unicorn from 64.0.0 to 76.0.0 by @dependabot[bot] in #3526
• fix: only write a comments part when the document has comments by @dolanmiu in #3544
• feat: native Word charts in docx/charts by @dolanmiu in #3545
• feat: combo, radar and bubble charts, and more chart options by @dolanmiu in #3546
• feat: charts in templates, with patchDocument by @dolanmiu in #3548
• feat: new data for a template's charts, with ChartDataPatch by @dolanmiu in #3549
• feat: stock, pie of pie and bar of pie charts, categories in groups, trendlines, error bars and more chart options by @dolanmiu in #3550
• docs: charts from Mermaid's pie and XY charts by @dolanmiu in #3551
• feat: support run properties on ImageRun by @holm in #3547
• chore: organise the demos into a folder for each topic by @dolanmiu in #3552
• feat: docx/math, with matrices, cases, equations lined up with numbers, and brackets of any characters by @dolanmiu in #3553
• fix: write Normal as the default paragraph style, so Pages draws math at its size, and draw angle brackets in LibreOffice by @dolanmiu in #3554
• chore: Version bump to 9.8.0 by @dolanmiu in #3555

New Contributors

• @slmnsh made their first contribution in #3505
• @omartuhintvs made their first contribution in #3476
• @theunal made their first contribution in #3221
• @fushanbobfan made their first contribution in #3540
• @holm made their first contribution in #3547

Full Changelog: 9.7.2...9.8.0