floodtide/dom-docx: Convert semantic HTML fragments to native, editable Word documents (OOXML) · GitHub

Charts & complex SVG (optional rasterizeInPlace):

• Rasterizes and complex (e.g. Highcharts) to PNG before conversion
• Recommended for charts: rasterizeInPlace: { scale: 2 } — supersamples at 2× density for sharper images in Word (default scale: 1; max 4)
• Browser: requires root. Clones off-screen by default so the live page is not mutated
• Node: uses the same Playwright/Chromium context as computed styles; ephemeral spawn pages mutate in place by default
• Simple inline SVG (rect + text bar charts) still converts natively without rasterization

Not supported in v0.1.x:

• External stylesheets on the inline path (use computed or inline all styles)
• Web fonts, CSS grid/float layout, forms,

   polish, 
  , table rowspan

• Header/footer first/even page variants; guaranteed multi-page layout fidelity
• Complex SVG (paths, gradients, ) unless rasterizeInPlace is used on a live rendered page

See AGENTS.md for HTML authoring tiers and API.md for full options.

Returns Promise (Node) with a valid .docx file.

import { convertHtmlToDocx, type ConvertOptions } from "dom-docx";

const docx = await convertHtmlToDocx(html, {
  pageSize: "a4",
  orientation: "landscape",
  margins: { top: 0.75, bottom: 0.75 }, // inches; omitted sides default to 1
  defaultFont: { family: "Georgia", sizePt: 11 },
  metadata: { title: "Q3 Report", creator: "Finance" },
  headerHtml: "
Confidential
",
  footerHtml: "
© 2026 ACME
",
  pageNumber: true,
  lang: "en-US",
  direction: "ltr",
  coverHtml: "", // page 1, before the TOC
  tocHtml: "
Introduction
", // your TOC; links jump to id="intro"
});

Option	Default	Description
styleSource	"inline"	"inline" parses style="" only (pure JS, fast). "computed" uses getComputedStyle. On Node this requires Playwright + Chromium; in the browser bundle it reads from the live DOM (no Playwright).
browser / page	—	Node only. Reuse an open Playwright browser or page (computed styles and/or rasterizeInPlace). Not used by dom-docx/browser.
rootSelector	—	Node only. CSS selector for the export root when converting element.innerHTML from a live Playwright page. Must match the node whose HTML you pass.
rasterizeInPlace	—	Rasterize / chart to PNG before conversion. Recommended: { scale: 2 } for chart exports. Node: Playwright page; browser: requires root. See API.md.
imageResolver	—	Hook to fetch non-data: (library never fetches on its own).
pageSize	"letter"	"letter", "a4" or { width, height } in inches.
orientation	"portrait"	"landscape" swaps dimensions.
margins	1 inch each	Per-side overrides in inches.
defaultFont	Arial 10.5pt	{ family, sizePt } for body text without explicit CSS.
metadata	—	title, subject, creator, keywords[], description → docProps/core.xml.
headerHtml / footerHtml	—	HTML fragments for page header/footer.
pageNumber	false	Appends centered Page N field to footer.
lang / direction	—	Spell-check locale; "rtl" for right-to-left.
coverHtml	—	HTML fragment rendered as a cover page — the first content, before the TOC, followed by an automatic page break. Inline styles + data: images (e.g. a logo). Header/footer/page number are suppressed on the cover page.
tocHtml	—	HTML fragment rendered as a table-of-contents “slot” — placed after the cover, before the body. You control the markup/styling (numbered, boxed, columns…); in-page links () jump to the matching id in the body. Add a trailing to put it on its own page.

Only data: URLs embed automatically. For http(s): or file paths, supply a resolver. You control fetch policy and security:

const docx = await convertHtmlToDocx(html, {
  imageResolver: async (src) => {
    const res = await fetch(src); // your allowlist / SSRF checks
    if (!res.ok) return null;
    return { data: new Uint8Array(await res.arrayBuffer()), type: "png" };
  },
});

For client-side conversion (returns a Blob). No Playwright. The bundle runs entirely in the user’s browser.

import { convertHtmlToDocx } from "dom-docx/browser";

// Inline styles: pass HTML string directly
const blob = await convertHtmlToDocx(htmlFragment, { styleSource: "inline" });

// Computed styles: render the fragment in the live DOM first, then convert
document.body.innerHTML = htmlFragment;
const blob2 = await convertHtmlToDocx(htmlFragment, { styleSource: "computed" });

// SPA export: pass the live root so computed paths match element.innerHTML
const root = document.querySelector(".page-body")!;
const blob3 = await convertHtmlToDocx(root.innerHTML, {
  styleSource: "computed",
  root,
});

// Charts (Highcharts, canvas): rasterize to PNG  on a clone, then convert
const blob4 = await convertHtmlToDocx(root.innerHTML, {
  styleSource: "computed",
  root,
  rasterizeInPlace: { scale: 2 }, // recommended for charts; default scale is 1
});

Browser-only options: root, document, rasterizeInPlace. Build: npm run build:browser → dist/browser/dom-docx.browser.js.

For advanced usage (buildDocxBuffer, custom StyleResolver, engine architecture), see API.md.

Optimized for Word-friendly semantic HTML: headings, paragraphs, lists, data tables, inline formatting, shaded callouts, simple flex rows.

Full authoring guide for agents: AGENTS.md.

dom-docx maps a practical HTML subset to native OOXML through a three-stage pipeline:

1. Style resolution: inline style="" (default) or browser computed styles
2. Visitor: Cheerio walk → docx paragraphs, tables, numbering, hyperlinks
3. Pack + patch: generate OOXML, patch list numbering and shaded-block alignment for LibreOffice/Word PDF export

Quality is driven by an autonomous loop rather than one-off visual checks:

• 30+ regression cases (defined in tools/generator.ts, run via npm run score:suite): human-validated layout fidelity (ink-projection structure comparison, 85.6% concordance with blind human quality ratings), plus guards for bad contrast, missing list markers, wrong text and imbalanced shaded blocks; raw pixel match is recorded as a regression tripwire
• Engine score: 50% visual (layout-based) + 35% editability (native structure, not 1×1 layout tables) + 15% compile speed
• OSS benchmark: same harness scores html-to-docx and @turbodocx/html-to-docx for ongoing comparison (BENCHMARK.md)

The default inline path is pure JavaScript (docx + cheerio + fflate) with no browser required. Playwright is Node-only: for styleSource: "computed" on the server and for the dev harness. The dom-docx/browser bundle never uses Playwright; computed styles come from the live page’s getComputedStyle.

Full scoring formulas, subscores, calibration and the agent iteration workflow: SCORING.md.

For contributors and harness runs (not required to use the library):

git clone … && npm install && npm run setup
npm run build              # dist/ for npm pack
npm run typecheck
npm run score:suite          # full visual + XML regression suite (cases: tools/generator.ts)
npm run score:suite:priority # fast subset of the same cases
# Run one case: SUITE_ONLY=rasterize-in-place-chart npm run score:suite
npm run score:benchmark     # vs html-to-docx + TurboDocx
npm run guard:config        # ConvertOptions OOXML checks

Prerequisites for the harness: LibreOffice (soffice) for PDF rasterization, Playwright Chromium (npm run setup).

MIT