# dom-docx
Convert semantic **HTML** to native, editable **docx files** (OOXML): paragraphs, runs, lists, tables, flex and images are all supported.
**Live demo:** [dom-docx.com](https://dom-docx.com/). Try the converter, browse showcases, read the learn guide.
Built with a visual regression loop: render HTML in Chromium, convert to docx, rasterize via LibreOffice, score layout + structural fidelity against a human-validated metric, iterate. Latest scores: [TEST-SCORES.md](./docs/TEST-SCORES.md) · methodology: [SCORING.md](./docs/SCORING.md).
## Install
```bash
npm install dom-docx
```
Requires **Node.js ≥ 20**. No browser or Playwright is needed for the default `inline` path.
### When is Playwright needed?
| Entry | `styleSource: "inline"` | `styleSource: "computed"` | `rasterizeInPlace` |
| -------------------------------- | ----------------------- | ---------------------------------------- | -------------------------------------------------- |
| **Node** (`dom-docx`) | Pure JS, no browser | **Playwright + Chromium** | **Playwright + Chromium** (same headless page) |
| **Browser** (`dom-docx/browser`) | Pure JS, no live DOM | **Live page**: native `getComputedStyle` | **Live page**: canvas/SVG → PNG `![]()
` in the tab |
On Node, `playwright` is an **optional peer dependency**. `npm install dom-docx` pulls only `docx`, `cheerio` and `fflate`. It is loaded lazily when you pass `styleSource: "computed"` or `rasterizeInPlace`. To use those paths, install Playwright and Chromium yourself, once:
```bash
npm install playwright
npx playwright install chromium
```
Playwright is also used by the **dev test harness** (not required to use the library). Contributors: `npm run setup` after clone.
LibreOffice is **not** needed to convert. It is only used for the visual test harness.
## Quick start
### Node
```typescript
import { writeFile } from "node:fs/promises";
import { convertHtmlToDocx } from "dom-docx";
const html = `
Quarterly Report
Revenue grew 12% year over year.
`;
const docx = await convertHtmlToDocx(html);
await writeFile("output.docx", docx);
```
Pass a **body fragment only** (no `` / `` / `` required). Defaults: US Letter, 1″ margins, Arial 10.5pt body text.
### Browser
```typescript
import { convertHtmlToDocx } from "dom-docx/browser";
const html = `
Quarterly Report
Revenue grew 12% year over year.
`;
const blob = await convertHtmlToDocx(html);
// e.g. trigger a download in the browser
const a = document.createElement("a");
a.href = URL.createObjectURL(blob);
a.download = "output.docx";
a.click();
```
No Playwright, no Node. This runs entirely in the user's tab. See [Browser bundle](#browser-bundle) below.
### CLI
Convert a file without writing any code:
```bash
npx dom-docx input.html -o output.docx
npx dom-docx input.html # writes input.docx next to it
cat fragment.html | npx dom-docx - -o - # stdin → binary stdout (pipelines)
npx dom-docx input.html -s computed # stylesheet/class HTML (needs playwright installed)
npm install -g dom-docx # optional: install globally, then run "dom-docx" without npx
```
Input is a **body HTML fragment**, same as the API. `--help` for all options.
## v1.x capability
**Supported (default** `styleSource: "inline"`**):**
- Headings, paragraphs, lists (``/`` including `list-style-type`), tables, links, inline formatting
- Block backgrounds, blockquotes, `
`, simple flex rows (≤4 items)
- `data:` images; remote images via your `imageResolver`
- Page size/orientation/margins, default font, metadata, header/footer HTML, page numbers, table of contents, lang/direction
- Low-complexity inline SVG (bars + text)
- CSS bar divs in table cells (background + height/width → native shaded bands)
**Advanced (optional** `styleSource: "computed"`**):**
- Resolves `