> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fonts

Fonts decide where lines break. If the layout measures text with a font that has different widths than Microsoft PowerPoint's, lines break in different places and text moves. Read this page before you deploy.

## How fonts are chosen

The layout asks a **font registry** for each family name in the deck (`Calibri`, `Arial` …). The registry gives a face, or a fallback. A font that the deck embeds is used before any other face of that name.

The library uses the **portable profile** in `@reductoai/portable-fonts`. It has open fonts with the same metrics as the Office fonts:

| Office font | Portable face |
| - | - |
| Calibri | Carlito |
| Cambria | Caladea |
| Arial, Helvetica | Liberation Sans |
| Times New Roman | Liberation Serif |
| Courier New | Liberation Mono |
| Cambria Math | STIX Two Math (other metrics) |

Plus script fallbacks for CJK and other scripts.

## Node

`registerPptxFonts()` from `@reductoai/pptx/node` registers fonts once per registry. `PowerPointPresentation.toPdf()` and `toPng()` call it for you; call it yourself before `runPptxPipelineFile`.

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.
3. Else (Linux servers, CI), it uses the portable profile and writes one warning:

```text theme={null}
[docx] macOS oracle fonts not found; using the bundled portable profile ...
```

The output is then deterministic on every machine.

Helvetica and Helvetica Neue always map to Liberation Sans, because Microsoft PowerPoint's output for those names follows the Arial metrics.

On a host with no system fonts at all, call `registerPortableFonts()` first.

### Use your own fonts on a server

If you have a licence for the Office fonts, put them in a folder with a `font-table.json`:

```json theme={null}
{
  "families": {
    "calibri": { "regular": "calibri-r", "bold": "calibri-b", "italic": "calibri-i", "boldItalic": "calibri-bi" }
  },
  "files": {
    "calibri-r": "calibri.ttf",
    "calibri-b": "calibrib.ttf",
    "calibri-i": "calibrii.ttf",
    "calibri-bi": "calibriz.ttf"
  }
}
```

Family keys are lower case. Then start your process with `DOCX_FONT_MIRROR=/path/to/folder`. `@reductoai/docx` and `@reductoai/pptx` read the same folder.

## Browser

A page cannot read system fonts, so you give the layout a **face provider**. It downloads only the faces that a deck uses, and only once.

```ts theme={null}
import { portableFaceProvider } from "@reductoai/pptx/browser";

const fonts = portableFaceProvider((file) => `/fonts/${file}`);
```

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. To serve other fonts, use `tableFaceProvider(table, urlFor)`.

A face download is async, but layout is sync. So a page lays out once to learn which faces the deck needs, fetches them, and lays out again. [JS API in the browser](https://docs.reducto.ai/office/pptx/js-api/browser.md) shows the steps. The [editor](https://docs.reducto.ai/office/pptx/ui/editor.md) does this for you.

## Embed a font in the deck

`presentation.embeddedFonts.add(typeface, faces)` stores TrueType or OpenType files in the deck, so Microsoft PowerPoint and the viewer show the font where it is not installed. A font whose licence forbids embedding is refused. `presentation.fonts` lists the typefaces the deck uses and whether each is embedded.

```ts theme={null}
import { readFile } from "node:fs/promises";
import { PowerPointPresentation } from "@reductoai/pptx/node";

const deck = await PowerPointPresentation.open("deck.pptx");
deck.embeddedFonts.add("Inter", {
  regular: new Uint8Array(await readFile("Inter-Regular.ttf")),
  bold: new Uint8Array(await readFile("Inter-Bold.ttf")),
});
await deck.save("deck-with-fonts.pptx");
```

> [!WARNING]
>
> Font files have licences. The portable profile is open (SIL OFL and similar). Do not serve or embed the Microsoft Office fonts unless your licence permits it.
