Skip to main content
Fonts decide where lines break. If the layout measures text with a font that has different widths than Word’s, lines break in different places and pages move. Read this page before you deploy.

How fonts are chosen

The layout asks a font registry for each family name in the document (Calibri, Times New Roman …). The registry gives a face, or a fallback. The library ships a portable profile in @reductoai/portable-fonts. It has open fonts with the same metrics as the Office fonts: Plus script fallbacks: Droid Sans Fallback for Chinese, Japanese and Korean, and a Noto face for each other script Word sets outside its Latin fonts (Arabic, Hebrew, Indic scripts, Thai, Lao, Khmer, Myanmar, Tibetan, Georgian, Armenian, Ethiopic and others). Greek and Cyrillic in a clone with no Greek or Cyrillic (Caladea, Gelasio, Selawik) take Times New Roman’s or Arial’s clone. These faces do not have the metrics of Word’s own script fonts, so lines in those scripts can break in other places. Selawik has no italic face, so Segoe UI italic is the upright face, slanted. A font with no clone (Aptos, Verdana, Tahoma) takes the face Word gives a missing font: Calibri’s clone for most sans fonts, Cambria’s for serif fonts. The licences are in the package: LICENSE.md, OFL-Gelasio.txt, OFL-Selawik.txt, OFL-Noto.txt and DROID-NOTICE.

Node

@reductoai/docx/node registers fonts the first time it lays out a document:
  1. If DOCX_FONT_MIRROR is set, it uses the portable profile plus the faces in that folder. The folder must contain a font-table.json (see below).
  2. Else, on a Mac with the Office fonts installed, it uses those fonts. This gives the closest match to Word.
  3. Else (Linux servers, CI), it uses the portable profile and writes one warning:
The output is then deterministic on every machine.

Use your own fonts on a server

For the document server, see Document server fonts: it reads a folder of font files and needs no font-table.json. If you have a license for the Office fonts, put them in a folder with a font-table.json:
Family keys are lower case. Then start your process with DOCX_FONT_MIRROR=/path/to/folder. The engine reads that folder once, when it loads. To lay out one document with other faces, give runPipeline or convertDocxToPdf a measurer whose FontRegistry has them (registerFontFile, registerBuiltinFamilies). That document then lays out with the registry’s faces and nothing else. A registry that adds no faces, such as the default one or registerPortableFonts alone, keeps the engine’s shared table at no extra cost. WordDocument takes no measurer: register the faces on defaultFontRegistry (from @reductoai/docx) before you open the document. A document opened after that, and a runPipeline or convertDocxToPdf call without a measurer, lays out with them.

Browser

A page cannot read system fonts, so you give the layout a face provider. It downloads only the faces that a document uses, and only once.
For production, serve the files from your own origin. Copy node_modules/@reductoai/portable-fonts/files to your static folder and point the URL there. Or serve them from the package with a route. In Next.js:
Then use portableFaceProvider((file) => /fonts/${file}). To serve other fonts, use tableFaceProvider(table, urlFor) with the same font-table.json format as DOCX_FONT_MIRROR.

Why layout runs twice

A face download is async, but layout is sync. So layoutDocxInBrowser lays out once to find the faces the document needs, downloads them, and lays out again. When all faces are already in the cache, it lays out once. You do not need to do anything for this; it explains the first-load time.
Font files have licenses. The portable profile is open (SIL OFL and similar). Do not serve the Microsoft Office fonts from a public site unless your license permits it.