# docxio

> JSX in, DOCX out. Generate Word documents with JSX syntax, powered by Rust and WASM.


## docs


### api

- [Components](/docs/api/components.md): Complete reference for all 23 JSX components available in docxio
- [Quick Reference](/docs/api/quick-reference.md): Single-page API cheat sheet for docxio
- [Render Functions](/docs/api/render.md): API reference for render, renderToStream, and other output functions
- [Template API](/docs/api/template.md): Load .docx templates and replace placeholders with dynamic content
- [Themes API](/docs/api/themes.md): Apply consistent fonts, colors, heading styles, and page margins via themes

### architecture

- [Architecture Overview](/docs/architecture/overview.md): Data flow from JSX to DOCX through the Rust WASM pipeline
- [Rust Crates](/docs/architecture/rust-crates.md): Layered workspace of 10 Rust crates powering docxio
- [Security](/docs/architecture/security.md): Security model including Rust guarantees, input validation, and CI auditing

### contributing

How to set up the development environment and contribute to docxio

- [Contributing](/docs/contributing.md): How to set up the development environment and contribute to docxio

### getting-started

- [Configuration](/docs/getting-started/configuration.md): Configure backend options, bundler plugins, and TypeScript settings
- [Installation](/docs/getting-started/installation.md): Install docxio and configure your project
- [Quick Start](/docs/getting-started/quick-start.md): Create your first .docx document with docxio in minutes

### guides

- [Data Components](/docs/guides/data-components.md): Higher-level components like DataTable, PageNumbers, Watermark, and more
- [Headers and Footers](/docs/guides/headers-footers.md): Add headers and footers to document sections
- [HTML and Markdown Export](/docs/guides/html-markdown-export.md): Convert docxio document trees to HTML or Markdown strings
- [Images](/docs/guides/images.md): Embed inline and floating images in documents
- [Lists](/docs/guides/lists.md): Create bullet and numbered lists with nesting support
- [Paragraphs and Formatting](/docs/guides/paragraphs-and-formatting.md): Create paragraphs, apply text formatting, and control alignment
- [Streaming](/docs/guides/streaming.md): Stream .docx bytes as a ReadableStream for HTTP responses
- [Styles and Themes](/docs/guides/styles-and-themes.md): Define reusable paragraph and character styles with theme support
- [Tables](/docs/guides/tables.md): Build tables with rows, cells, merging, and borders
- [Templates](/docs/guides/templates.md): Load .docx templates and replace placeholder tokens with dynamic values

### packages

- [@docxio/bun](/docs/packages/bun.md): Bun build plugin for WASM resolution and JSX configuration
- [@docxio/html](/docs/packages/html.md): HTML and Markdown export for docxio document trees
- [@docxio/node](/docs/packages/node.md): Native Node.js bindings via napi-rs for server-side document generation
- [@docxio/wasm-minimal](/docs/packages/wasm-minimal.md): Minimal WASM binary for browser-side OOXML generation without ZIP
- [@docxio/zip](/docs/packages/zip.md): JavaScript-side ZIP assembly for the minimal WASM backend

### reference

- [Glossary](/docs/reference/glossary.md): Terminology used in docxio documentation


---

# Full Documentation Content

# Components

Complete reference for all 23 JSX components available in docxio.

## Document structure[​](#document-structure "Direct link to Document structure")

### `<document>`[​](#document "Direct link to document")

Root element. Maps to `w:document`.

| Prop               | Type             | Description                                      |
| ------------------ | ---------------- | ------------------------------------------------ |
| `creator`          | `string`         | Author metadata                                  |
| `title`            | `string`         | Document title metadata                          |
| `description`      | `string`         | Subject/description metadata                     |
| `keywords`         | `string`         | Keywords metadata                                |
| `styles`           | `DocumentStyles` | Custom paragraph and character style definitions |
| `useDefaultStyles` | `boolean`        | Include default Word styles (default: `true`)    |
| `theme`            | `Theme`          | Theme preset for document-wide styling           |

### `<section>`[​](#section "Direct link to section")

Page layout unit. Maps to `w:sectPr`.

| Prop            | Type                                  | Description                                                     |
| --------------- | ------------------------------------- | --------------------------------------------------------------- |
| `pageSize`      | `{ width?: number; height?: number }` | Page dimensions in twips                                        |
| `margins`       | `PageMargins`                         | Page margins (top, right, bottom, left, header, footer, gutter) |
| `orientation`   | `"portrait" \| "landscape"`           | Page orientation                                                |
| `columns`       | `number \| ColumnDef[]`               | Number of columns or column definitions                         |
| `columnSpace`   | `number`                              | Space between columns in twips                                  |
| `lineNumbers`   | `object`                              | Line numbering config                                           |
| `isLastSection` | `boolean`                             | Suppress trailing page break                                    |

## Text content[​](#text-content "Direct link to Text content")

### `<paragraph>`[​](#paragraph "Direct link to paragraph")

Maps to `w:p`.

| Prop              | Type             | Description                                                                |
| ----------------- | ---------------- | -------------------------------------------------------------------------- |
| `alignment`       | `Alignment`      | `"left"`, `"center"`, `"right"`, `"justify"`, `"start"`, `"end"`, `"both"` |
| `spacing`         | `Spacing`        | `{ before?, after?, line?, lineRule? }`                                    |
| `indentation`     | `Indentation`    | `{ left?, right?, firstLine?, hanging? }`                                  |
| `style`           | `string`         | Named paragraph style                                                      |
| `numbering`       | `NumberingProps` | List numbering reference                                                   |
| `border`          | `Borders`        | Paragraph borders                                                          |
| `shading`         | `Shading`        | Background fill                                                            |
| `keepNext`        | `boolean`        | Keep with next paragraph                                                   |
| `keepLines`       | `boolean`        | Keep lines together                                                        |
| `pageBreakBefore` | `boolean`        | Page break before                                                          |
| `widowControl`    | `boolean`        | Widow/orphan control                                                       |
| `outlineLevel`    | `number`         | Outline level for TOC                                                      |
| `bidi`            | `boolean`        | Right-to-left direction                                                    |

### `<run>`[​](#run "Direct link to run")

Text run. Maps to `w:r`.

| Prop               | Type                        | Description                     |
| ------------------ | --------------------------- | ------------------------------- |
| `bold`             | `boolean`                   | Bold                            |
| `italic`           | `boolean`                   | Italic                          |
| `underline`        | `UnderlineStyle \| boolean` | Underline style                 |
| `strike`           | `boolean`                   | Strikethrough                   |
| `doubleStrike`     | `boolean`                   | Double strikethrough            |
| `fontSize`         | `number`                    | Size in half-points (24 = 12pt) |
| `fontFamily`       | `string`                    | Font name                       |
| `color`            | `string`                    | Hex color (e.g., `"FF0000"`)    |
| `highlight`        | `HighlightColor`            | Background highlight            |
| `superscript`      | `boolean`                   | Superscript                     |
| `subscript`        | `boolean`                   | Subscript                       |
| `allCaps`          | `boolean`                   | All capitals                    |
| `smallCaps`        | `boolean`                   | Small capitals                  |
| `characterSpacing` | `number`                    | Spacing in twips                |
| `emboss`           | `boolean`                   | Emboss effect                   |
| `imprint`          | `boolean`                   | Imprint effect                  |
| `shadow`           | `boolean`                   | Shadow                          |
| `style`            | `string`                    | Named character style           |
| `bidi`             | `boolean`                   | Right-to-left                   |
| `lang`             | `string`                    | Language tag                    |

### `<heading>`[​](#heading "Direct link to heading")

Heading paragraph. Maps to `w:p` + `w:pStyle`.

| Prop        | Type             | Description         |
| ----------- | ---------------- | ------------------- |
| `level`     | `1-6`            | Heading level       |
| `alignment` | `Alignment`      | Text alignment      |
| `spacing`   | `Spacing`        | Paragraph spacing   |
| `numbering` | `NumberingProps` | Numbering reference |

## Tables[​](#tables "Direct link to Tables")

### `<table>`[​](#table "Direct link to table")

Maps to `w:tbl`. See [Tables guide](/docs/guides/tables.md).

### `<row>`[​](#row "Direct link to row")

Maps to `w:tr`. Props: `header`, `height`, `heightRule`, `cantSplit`.

### `<cell>`[​](#cell "Direct link to cell")

Maps to `w:tc`. Props: `width`, `widthType`, `columnSpan`, `verticalMerge`, `verticalAlignment`, `shading`, `borders`, `margins`.

## Media[​](#media "Direct link to Media")

### `<image>`[​](#image "Direct link to image")

Maps to `w:drawing`. See [Images guide](/docs/guides/images.md).

Props: `src` (required), `width`, `height`, `widthPt`, `heightPt`, `altText`, `floating`, `wrapText`, `floatPosition`, `format`.

## Links and bookmarks[​](#links-and-bookmarks "Direct link to Links and bookmarks")

### `<hyperlink>`[​](#hyperlink "Direct link to hyperlink")

Maps to `w:hyperlink`.

| Prop      | Type     | Description            |
| --------- | -------- | ---------------------- |
| `url`     | `string` | External URL           |
| `anchor`  | `string` | Internal bookmark name |
| `tooltip` | `string` | Hover tooltip          |

### `<bookmark>`[​](#bookmark "Direct link to bookmark")

Maps to `w:bookmarkStart/End`.

| Prop   | Type     | Description                 |
| ------ | -------- | --------------------------- |
| `name` | `string` | **Required.** Bookmark name |
| `id`   | `string` | Unique identifier           |

## Headers and footers[​](#headers-and-footers "Direct link to Headers and footers")

### `<header>` / `<footer>`[​](#header--footer "Direct link to header--footer")

| Prop   | Type                             | Description                          |
| ------ | -------------------------------- | ------------------------------------ |
| `type` | `"default" \| "first" \| "even"` | When this header/footer is displayed |

## Lists[​](#lists "Direct link to Lists")

### `<numbered-list>`[​](#numbered-list "Direct link to numbered-list")

Props: `format` (NumberingFormat), `start` (number), `reference` (string).

### `<bullet-list>`[​](#bullet-list "Direct link to bullet-list")

Props: `reference` (string).

### `<list-item>`[​](#list-item "Direct link to list-item")

Props: `level` (0-8), `numbering` (NumberingProps).

## Annotations[​](#annotations "Direct link to Annotations")

### `<comment>`[​](#comment "Direct link to comment")

| Prop     | Type     | Description    |
| -------- | -------- | -------------- |
| `author` | `string` | Comment author |
| `date`   | `string` | Comment date   |
| `id`     | `string` | Comment ID     |

### `<footnote>`[​](#footnote "Direct link to footnote")

Props: `id` (string). Content provided as children.

## Fields[​](#fields "Direct link to Fields")

### `<field>`[​](#field "Direct link to field")

Maps to `w:fldChar`.

| Prop     | Type     | Description                                  |
| -------- | -------- | -------------------------------------------- |
| `code`   | `string` | Field code: `"PAGE"`, `"NUMPAGES"`, `"DATE"` |
| `format` | `string` | Display format                               |

## Breaks and whitespace[​](#breaks-and-whitespace "Direct link to Breaks and whitespace")

| Component       | OOXML              | Props                        |
| --------------- | ------------------ | ---------------------------- |
| `<pagebreak>`   | `w:br type=page`   | --                           |
| `<linebreak>`   | `w:br`             | --                           |
| `<columnbreak>` | `w:br type=column` | --                           |
| `<tab>`         | `w:tab`            | --                           |
| `<tabstop>`     | `w:tabs`           | `position`, `type`, `leader` |


---

# Quick Reference

Single-page cheat sheet for the docxio API.

## Components (23)[​](#components-23 "Direct link to Components (23)")

### Document Structure[​](#document-structure "Direct link to Document Structure")

| Component    | Key Props                                                                                      |
| ------------ | ---------------------------------------------------------------------------------------------- |
| `<document>` | `creator`, `title`, `description`, `keywords`, `styles`, `useDefaultStyles`, `theme`           |
| `<section>`  | `pageSize`, `margins`, `orientation`, `columns`, `columnSpace`, `lineNumbers`, `isLastSection` |

### Text[​](#text "Direct link to Text")

| Component     | Key Props                                                                                                                                                            |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<paragraph>` | `alignment`, `spacing`, `indentation`, `style`, `numbering`, `border`, `shading`, `keepNext`, `keepLines`, `pageBreakBefore`, `widowControl`, `outlineLevel`, `bidi` |
| `<run>`       | `bold`, `italic`, `underline`, `strike`, `fontSize`, `fontFamily`, `color`, `highlight`, `superscript`, `subscript`, `allCaps`, `smallCaps`, `style`, `lang`         |
| `<heading>`   | `level` (1-6), `alignment`, `spacing`, `numbering`                                                                                                                   |

### Tables[​](#tables "Direct link to Tables")

| Component | Key Props                                                                                                            |
| --------- | -------------------------------------------------------------------------------------------------------------------- |
| `<table>` | `width`, `widthType`, `borders`, `alignment`, `layout`, `style`, `indent`, `cellMargins`, `float`                    |
| `<row>`   | `header`, `height`, `heightRule`, `cantSplit`                                                                        |
| `<cell>`  | `width`, `widthType`, `borders`, `shading`, `verticalMerge`, `verticalAlignment`, `columnSpan`, `rowSpan`, `margins` |

### Media[​](#media "Direct link to Media")

| Component | Key Props                                                                                                                |
| --------- | ------------------------------------------------------------------------------------------------------------------------ |
| `<image>` | `src` (required), `width`, `height`, `widthPt`, `heightPt`, `altText`, `floating`, `wrapText`, `floatPosition`, `format` |

### Links and Bookmarks[​](#links-and-bookmarks "Direct link to Links and Bookmarks")

| Component     | Key Props                  |
| ------------- | -------------------------- |
| `<hyperlink>` | `url`, `anchor`, `tooltip` |
| `<bookmark>`  | `name` (required), `id`    |

### Headers and Footers[​](#headers-and-footers "Direct link to Headers and Footers")

| Component  | Key Props                                    |
| ---------- | -------------------------------------------- |
| `<header>` | `type`: `"default"` \| `"first"` \| `"even"` |
| `<footer>` | `type`: `"default"` \| `"first"` \| `"even"` |

### Lists[​](#lists "Direct link to Lists")

| Component         | Key Props                      |
| ----------------- | ------------------------------ |
| `<numbered-list>` | `format`, `start`, `reference` |
| `<bullet-list>`   | `reference`                    |
| `<list-item>`     | `level` (0-8), `numbering`     |

### Annotations[​](#annotations "Direct link to Annotations")

| Component    | Key Props              |
| ------------ | ---------------------- |
| `<comment>`  | `author`, `date`, `id` |
| `<footnote>` | `id`                   |

### Breaks and Whitespace[​](#breaks-and-whitespace "Direct link to Breaks and Whitespace")

| Component       | Key Props                    |
| --------------- | ---------------------------- |
| `<pagebreak>`   | --                           |
| `<linebreak>`   | --                           |
| `<columnbreak>` | --                           |
| `<tab>`         | --                           |
| `<tabstop>`     | `position`, `type`, `leader` |

### Fields[​](#fields "Direct link to Fields")

| Component | Key Props                                                           |
| --------- | ------------------------------------------------------------------- |
| `<field>` | `code` (required: `"PAGE"`, `"NUMPAGES"`, `"DATE"`, etc.), `format` |

## Render Functions[​](#render-functions "Direct link to Render Functions")

```
// Core render - returns raw .docx bytes
render(tree: DocumentNode, options?: RenderOptions): Promise<Uint8Array>

// Write directly to file (Node.js/Bun/Deno)
renderToFile(tree: DocumentNode, path: string): Promise<void>

// Node.js Buffer
renderToBuffer(tree: DocumentNode): Promise<Buffer>

// Browser Blob (with correct MIME type)
renderToBlob(tree: DocumentNode): Promise<Blob>

// Streaming (64KB chunks)
renderToReadableStream(tree: DocumentNode, options?: RenderOptions): ReadableStream<Uint8Array>

// Base64 string
renderToBase64(tree: DocumentNode, options?: RenderOptions): Promise<string>

// Patch {{placeholder}} tokens in an existing .docx
patchDocument(templateBytes: Uint8Array, replacements: Record<string, string>): Promise<Uint8Array>
```

### RenderOptions[​](#renderoptions "Direct link to RenderOptions")

```
interface RenderOptions {
  strict?: boolean;              // Throw on validation errors (default: false)
  backend?: "minimal" | "full" | "auto";  // WASM backend (default: "auto")
}
```

## Template Functions[​](#template-functions "Direct link to Template Functions")

```
// Load and parse a .docx template, detecting {{slot}} placeholders
loadTemplate(bytes: Uint8Array): Promise<ParsedTemplate>

// Fill template slots with string values or DocumentNode content
fillTemplate(
  template: ParsedTemplate,
  values: Record<string, SlotValue>,
  options?: { openDelim?: string; closeDelim?: string }
): Promise<Uint8Array>
```

### Template JSX Components[​](#template-jsx-components "Direct link to Template JSX Components")

```
// Declarative template filling
<Template src={parsedTemplate} values={{ title: "Hello" }}>
  <Slot name="content">
    <paragraph><run bold>Rich content here</run></paragraph>
  </Slot>
</Template>
```

## TypeScript Config[​](#typescript-config "Direct link to TypeScript Config")

```
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "docxio"
  }
}
```

## Common Patterns[​](#common-patterns "Direct link to Common Patterns")

### Minimal Document[​](#minimal-document "Direct link to Minimal Document")

```
import { render } from "docxio";

const doc = (
  <document>
    <section>
      <paragraph><run>Hello, World!</run></paragraph>
    </section>
  </document>
);

const bytes = await render(doc);
```

### Table[​](#table "Direct link to Table")

```
<table width="100%" widthType="pct" layout="fixed">
  <row header>
    <cell shading={{ fill: "EEEEEE" }}><paragraph><run bold>Name</run></paragraph></cell>
    <cell shading={{ fill: "EEEEEE" }}><paragraph><run bold>Value</run></paragraph></cell>
  </row>
  <row>
    <cell><paragraph><run>Item</run></paragraph></cell>
    <cell><paragraph><run>100</run></paragraph></cell>
  </row>
</table>
```

### Styled Document[​](#styled-document "Direct link to Styled Document")

```
<document
  title="Report"
  creator="docxio"
  theme={myTheme}
  styles={{
    paragraphStyles: [{
      id: "CustomHeading",
      name: "Custom Heading",
      alignment: "center",
      runProps: { bold: true, fontSize: 32, color: "2E74B5" },
    }],
  }}
>
  <section orientation="portrait" margins={{ top: 1440, bottom: 1440, left: 1440, right: 1440 }}>
    <heading level={1}>Title</heading>
    <paragraph style="CustomHeading"><run>Styled paragraph</run></paragraph>
  </section>
</document>
```

### Template Filling[​](#template-filling "Direct link to Template Filling")

```
import { loadTemplate, fillTemplate } from "docxio";
import { readFile } from "node:fs/promises";

const bytes = await readFile("template.docx");
const tpl = await loadTemplate(new Uint8Array(bytes));

// String replacement
const result = await fillTemplate(tpl, {
  title: "Quarterly Report",
  date: "2026-03-30",
});

// Or JSX-based with <Template> + <Slot>
const doc = (
  <Template src={tpl} values={{ title: "Report" }}>
    <Slot name="body">
      <paragraph><run>Dynamic content</run></paragraph>
    </Slot>
  </Template>
);
const docBytes = await render(doc);
```


---

# Render Functions

All render functions accept a docxio JSX document tree as the first argument.

## render[​](#render "Direct link to render")

The primary render function. Returns a `Uint8Array` containing the `.docx` file bytes.

```
import { render } from "docxio";

const bytes: Uint8Array = await render(doc);
const bytes: Uint8Array = await render(doc, { backend: "minimal" });
```

**Signature:**

```
function render(
  tree: DocumentNode,
  options?: { backend?: "auto" | "minimal" | "full" }
): Promise<Uint8Array>;
```

## renderToFile[​](#rendertofile "Direct link to renderToFile")

Renders and writes directly to disk. Available in Node.js, Bun, and Deno.

```
import { renderToFile } from "docxio";

await renderToFile(doc, "report.docx");
```

**Signature:**

```
function renderToFile(tree: DocumentNode, path: string): Promise<void>;
```

## renderToBuffer[​](#rendertobuffer "Direct link to renderToBuffer")

Returns a Node.js `Buffer`.

```
import { renderToBuffer } from "docxio";

const buf: Buffer = await renderToBuffer(doc);
```

**Signature:**

```
function renderToBuffer(tree: DocumentNode): Promise<Buffer>;
```

## renderToBlob[​](#rendertoblob "Direct link to renderToBlob")

Returns a browser `Blob` with the correct MIME type.

```
import { renderToBlob } from "docxio";

const blob: Blob = await renderToBlob(doc);
const url = URL.createObjectURL(blob);
```

**Signature:**

```
function renderToBlob(tree: DocumentNode): Promise<Blob>;
```

## renderToReadableStream[​](#rendertoreadablestream "Direct link to renderToReadableStream")

Returns a web `ReadableStream<Uint8Array>` for streaming HTTP responses.

```
import { renderToReadableStream } from "docxio";

const stream: ReadableStream<Uint8Array> = renderToReadableStream(doc);
return new Response(stream, {
  headers: {
    "Content-Type":
      "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  },
});
```

**Signature:**

```
function renderToReadableStream(tree: DocumentNode): ReadableStream<Uint8Array>;
```

See the [Streaming guide](/docs/guides/streaming.md) for more examples.

## renderToBase64[​](#rendertobase64 "Direct link to renderToBase64")

Returns a base64-encoded string of the `.docx` bytes.

```
import { renderToBase64 } from "docxio";

const base64: string = await renderToBase64(doc);
```

**Signature:**

```
function renderToBase64(tree: DocumentNode): Promise<string>;
```

## transformTree[​](#transformtree "Direct link to transformTree")

Transforms a JSX tree into the Rust-compatible format without rendering. Useful for debugging or inspecting the intermediate representation.

```
import { transformTree } from "docxio";

const transformed = transformTree(doc);
console.log(JSON.stringify(transformed, null, 2));
```

**Signature:**

```
function transformTree(tree: DocumentNode): DocumentNode;
```

## initWasm[​](#initwasm "Direct link to initWasm")

Pre-initializes the WASM module. Call once at startup to avoid cold-start latency on the first render.

```
import { initWasm } from "docxio";

await initWasm();
```

**Signature:**

```
function initWasm(): Promise<void>;
```


---

# Template API

The template API lets you load existing `.docx` files and replace `{{placeholder}}` tokens with dynamic content.

## loadTemplate[​](#loadtemplate "Direct link to loadTemplate")

Parses a `.docx` file and scans for `{{placeholder}}` tokens.

```
import { loadTemplate } from "docxio";

const tpl = await loadTemplate(templateBytes);
console.log(tpl.slots); // ["title", "author", "content"]
```

**Signature:**

```
function loadTemplate(bytes: Uint8Array): Promise<{
  slots: string[];
  // internal template state
}>;
```

**Parameters:**

* `bytes` -- the raw bytes of a `.docx` file (e.g., from `fs.readFileSync` or `Bun.file().bytes()`)

**Returns:** A template object containing:

* `slots` -- array of placeholder names found in the document (e.g., `["title", "date"]` for a template with `{{title}}` and `{{date}}`)

## fillTemplate[​](#filltemplate "Direct link to fillTemplate")

Replaces placeholder slots with string values and returns the patched `.docx` bytes.

```
import { fillTemplate } from "docxio";

const patched: Uint8Array = await fillTemplate(tpl, {
  title: "Quarterly Report",
  author: "Jane Doe",
});

await Bun.write("filled.docx", patched);
```

**Signature:**

```
function fillTemplate(
  template: Template,
  values: Record<string, string>
): Promise<Uint8Array>;
```

## Template component[​](#template-component "Direct link to Template component")

JSX component for template-based documents. Supports both string replacements (via `values`) and structured content (via `<Slot>` children).

```
import { Template, Slot, render } from "docxio";

const doc = (
  <Template src={tpl} values={{ title: "Report" }}>
    <Slot name="content">
      <paragraph><run bold>Rich content here</run></paragraph>
    </Slot>
  </Template>
);

const bytes = await render(doc);
```

**Props:**

| Prop       | Type                     | Description                               |
| ---------- | ------------------------ | ----------------------------------------- |
| `src`      | Template object          | Template returned by `loadTemplate`       |
| `values`   | `Record<string, string>` | String values for simple text replacement |
| `children` | `Slot` elements          | Structured content slots                  |

## Slot component[​](#slot-component "Direct link to Slot component")

Injects structured JSX content into a named template placeholder. The entire paragraph containing `{{name}}` is replaced with the slot's children.

```
<Slot name="summary">
  <paragraph><run>This replaces the summary placeholder.</run></paragraph>
  <table borders="single">
    <row>
      <cell><paragraph><run>Data</run></paragraph></cell>
    </row>
  </table>
</Slot>
```

**Props:**

| Prop       | Type         | Description                                                       |
| ---------- | ------------ | ----------------------------------------------------------------- |
| `name`     | `string`     | **Required.** Name of the placeholder to fill (without `{{` `}}`) |
| `children` | JSX elements | Block-level content to insert                                     |

## SlotValue type[​](#slotvalue-type "Direct link to SlotValue type")

When working with templates programmatically:

```
type SlotValue = string | DocumentNode;
```

* `string` values replace `{{placeholder}}` text inline, preserving surrounding formatting
* `DocumentNode` values replace the entire containing paragraph with rendered content

## Example workflow[​](#example-workflow "Direct link to Example workflow")

```
import { loadTemplate, fillTemplate, render, Template, Slot } from "docxio";

// 1. Load the template
const bytes = await Bun.file("template.docx").bytes();
const tpl = await loadTemplate(bytes);

// 2a. Simple text replacement
const simple = await fillTemplate(tpl, { title: "Report", date: "2025-01-01" });

// 2b. Rich content replacement
const rich = await render(
  <Template src={tpl} values={{ title: "Report" }}>
    <Slot name="body">
      <heading level={2}><run>Summary</run></heading>
      <paragraph><run>Detailed content with tables, images, etc.</run></paragraph>
    </Slot>
  </Template>
);
```


---

# Themes API

Themes apply consistent fonts, colors, heading styles, and page margins across a document.

## Using a theme[​](#using-a-theme "Direct link to Using a theme")

```
import { corporate } from "docxio";

<document theme={corporate}>
  <section>
    <heading level={1}><run>Themed Document</run></heading>
    <paragraph><run>Body text inherits theme fonts and spacing.</run></paragraph>
  </section>
</document>
```

## Built-in themes[​](#built-in-themes "Direct link to Built-in themes")

### corporate[​](#corporate "Direct link to corporate")

Professional business styling with Calibri fonts and blue tones.

```
import { corporate } from "docxio";
```

* Fonts: Calibri (heading, body), Courier New (mono)
* Primary: `#1F4E79` | Secondary: `#2E75B6` | Accent: `#ED7D31`
* Heading 1: 18pt bold, navy | Heading 2: 14pt bold, blue

### academic[​](#academic "Direct link to academic")

Formal academic document styling with serif fonts.

```
import { academic } from "docxio";
```

### minimal[​](#minimal "Direct link to minimal")

Clean, sparse styling with generous whitespace.

```
import { minimal } from "docxio";
```

## Theme interface[​](#theme-interface "Direct link to Theme interface")

```
interface Theme {
  name: string;
  fonts: {
    heading: string;  // e.g., "Calibri"
    body: string;     // e.g., "Calibri"
    mono: string;     // e.g., "Courier New"
  };
  colors: {
    primary: string;    // Hex without # (e.g., "1F4E79")
    secondary: string;
    accent: string;
    text: string;
    textLight: string;
    background: string;
  };
  headingStyles: Record<1 | 2 | 3 | 4 | 5 | 6, HeadingThemeStyle>;
  paragraph: {
    fontSize?: number;      // Half-points (22 = 11pt)
    lineSpacing?: number;   // Twips
    spacingAfter?: number;  // Twips
  };
  table: {
    borderStyle?: string;
    borderColor?: string;
    headerBackground?: string;
    headerColor?: string;
  };
  page: {
    marginTop?: number;     // Twips
    marginRight?: number;
    marginBottom?: number;
    marginLeft?: number;
  };
}
```

### HeadingThemeStyle[​](#headingthemestyle "Direct link to HeadingThemeStyle")

```
interface HeadingThemeStyle {
  fontSize?: number;       // Half-points
  bold?: boolean;
  italic?: boolean;
  color?: string;          // Hex without #
  spacingBefore?: number;  // Twips
  spacingAfter?: number;   // Twips
}
```

## Creating a custom theme[​](#creating-a-custom-theme "Direct link to Creating a custom theme")

```
import type { Theme } from "docxio";

const ocean: Theme = {
  name: "ocean",
  fonts: {
    heading: "Segoe UI",
    body: "Segoe UI",
    mono: "Consolas",
  },
  colors: {
    primary: "006994",
    secondary: "40B5AD",
    accent: "FF6B6B",
    text: "1A1A2E",
    textLight: "7C8DB0",
    background: "FFFFFF",
  },
  headingStyles: {
    1: { fontSize: 36, bold: true, color: "006994", spacingBefore: 240, spacingAfter: 120 },
    2: { fontSize: 28, bold: true, color: "40B5AD", spacingBefore: 200, spacingAfter: 100 },
    3: { fontSize: 24, bold: true, color: "006994", spacingBefore: 160, spacingAfter: 80 },
    4: { fontSize: 22, bold: true, color: "40B5AD", spacingBefore: 120, spacingAfter: 60 },
    5: { fontSize: 20, bold: true, italic: true, color: "7C8DB0", spacingBefore: 100, spacingAfter: 40 },
    6: { fontSize: 20, italic: true, color: "7C8DB0", spacingBefore: 80, spacingAfter: 40 },
  },
  paragraph: {
    fontSize: 22,
    lineSpacing: 276,
    spacingAfter: 160,
  },
  table: {
    borderStyle: "single",
    borderColor: "006994",
    headerBackground: "006994",
    headerColor: "FFFFFF",
  },
  page: {
    marginTop: 1440,
    marginRight: 1440,
    marginBottom: 1440,
    marginLeft: 1440,
  },
};
```

See the [Styles and Themes guide](/docs/guides/styles-and-themes.md) for more usage examples.


---

# Architecture Overview

## Data flow[​](#data-flow "Direct link to Data flow")

```
JSX → createElement() → JS tree → serde-wasm-bindgen → Rust DocumentTree
    → docxio-ooxml XML → docxio-core ZIP → Uint8Array
```

```
┌──────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  JSX / TSX   │ ──► │  JS Object Tree  │ ──► │  Rust via WASM  │
│  components  │     │  (DocumentNode)  │     │  docxio-core    │
└──────────────┘     └──────────────────┘     └────────┬────────┘
                                                       │
                                              ┌────────▼────────┐
                                              │  OOXML XML +    │
                                              │  ZIP packaging  │
                                              │  → Uint8Array   │
                                              └─────────────────┘
```

### Step-by-step[​](#step-by-step "Direct link to Step-by-step")

1. **JSX authoring** -- Developers write documents using JSX syntax with `<document>`, `<paragraph>`, `<run>`, etc.
2. **createElement** -- Bun/tsc transpiles JSX to `docxio/jsx-runtime` calls, producing a plain JS object tree.
3. **Tree transform** -- The `transformTree` function normalizes the JS tree for the Rust side.
4. **FFI boundary** -- The tree crosses into WASM via a single `serde-wasm-bindgen` call (no JSON.stringify overhead).
5. **XML generation** -- `docxio-ooxml` generates OOXML XML parts (document.xml, styles.xml, numbering.xml, etc.) using the `quick-xml` writer API.
6. **ZIP packaging** -- `docxio-core` assembles all XML parts plus media files into a `.docx` ZIP archive.
7. **Return** -- The ZIP bytes are returned as a `Uint8Array` to JavaScript.

## Package structure[​](#package-structure "Direct link to Package structure")

### TypeScript packages[​](#typescript-packages "Direct link to TypeScript packages")

| Package                | Size            | Role                                             |
| ---------------------- | --------------- | ------------------------------------------------ |
| `docxio`               | 15 KB JS + WASM | Core: JSX runtime, transformer, render functions |
| `@docxio/html`         | \~5 KB          | HTML and Markdown export                         |
| `@docxio/zip`          | \~8 KB          | JS-side ZIP assembly for minimal backend         |
| `@docxio/bun`          | \~2 KB          | Bun build plugin                                 |
| `@docxio/node`         | native          | napi-rs server binding                           |
| `@docxio/wasm-minimal` | 441 KB          | Minimal WASM binary                              |

### Rust crates[​](#rust-crates "Direct link to Rust crates")

```
docxio-types        → Shared document model (serde + tsify)
    ↑
docxio-ooxml        → OOXML XML generation (quick-xml)
    ↑
docxio-core         → Orchestration: tree → XML → ZIP
    ↑
├── docxio-wasm          → Full WASM binding (920 KB)
├── docxio-wasm-minimal  → Minimal WASM binding (441 KB)
├── docxio-napi          → Native Node.js binding (napi-rs)
├── docxio-cli           → CLI tool (clap)
├── docxio-pdf           → PDF export (planned)
├── docxio-bench         → Benchmarks (criterion)
└── docxio-fuzz          → Fuzz testing
```

See [Rust Crates](/docs/architecture/rust-crates.md) for detailed crate responsibilities.

## Design principles[​](#design-principles "Direct link to Design principles")

* **Single FFI call** -- The entire document tree crosses the WASM boundary once, avoiding per-element overhead.
* **No React dependency** -- The JSX factory is a simple `createElement` function. Documents are static trees, not reactive components.
* **Layered crates** -- Each Rust crate has a single responsibility. `docxio-types` has no dependencies on XML or ZIP.
* **Modular WASM** -- The minimal build excludes ZIP, template, and validation code for smaller browser bundles.
* **XML safety** -- All user text is escaped via `quick-xml`. No string concatenation for XML generation.


---

# Rust Crates

The Rust side is organized as a layered workspace with 10 crates. Each crate has a single responsibility.

## Dependency graph[​](#dependency-graph "Direct link to Dependency graph")

```
docxio-types
    ↑
docxio-ooxml
    ↑
docxio-core
    ↑
├── docxio-wasm
├── docxio-wasm-minimal
├── docxio-napi
├── docxio-cli
├── docxio-pdf
├── docxio-bench
└── docxio-fuzz
```

## Crate responsibilities[​](#crate-responsibilities "Direct link to Crate responsibilities")

### docxio-types[​](#docxio-types "Direct link to docxio-types")

Shared document model types. Defines `DocumentTree`, `DocumentNode`, and all property structs (`ParagraphProps`, `RunProps`, `TableProps`, etc.).

* Derives `serde::Serialize` and `serde::Deserialize` with `rename_all = "camelCase"` for JS interop
* No XML or ZIP dependencies
* Used by every other crate in the workspace

### docxio-ooxml[​](#docxio-ooxml "Direct link to docxio-ooxml")

OOXML XML generation using `quick-xml`. Stateless functions that take typed Rust structs and produce XML byte output.

Key modules:

* `document_xml.rs` -- `word/document.xml`
* `styles_xml.rs` -- `word/styles.xml`
* `numbering_xml.rs` -- `word/numbering.xml`
* `header_xml.rs` / `footer_xml.rs` -- header/footer parts
* `drawing_xml.rs` -- image drawing elements
* `relationships.rs` -- `.rels` relationship files
* `content_types.rs` -- `[Content_Types].xml`
* `sanitize` module -- validates and clamps colors, sizes, dimensions to OOXML spec ranges

### docxio-core[​](#docxio-core "Direct link to docxio-core")

Orchestration layer. Walks the document tree, calls `docxio-ooxml` to generate XML parts, and assembles them into a ZIP archive.

Key modules:

* `render.rs` -- Tree walker, calls OOXML generators
* `builder.rs` -- Document builder API
* `parser.rs` -- JSON-to-DocumentTree parsing
* `template.rs` -- Template patching (`{{placeholder}}` replacement)
* `validate.rs` -- OOXML structure validation
* `media.rs` -- Image registry and embedding
* `rel_manager.rs` -- Relationship ID management

### docxio-wasm[​](#docxio-wasm "Direct link to docxio-wasm")

Full WebAssembly binding (\~920 KB). Exposes `generate()`, `patch()`, and `validate()` entry points via `wasm-bindgen`. Includes ZIP packaging, template engine, and validator.

### docxio-wasm-minimal[​](#docxio-wasm-minimal "Direct link to docxio-wasm-minimal")

Minimal WebAssembly binding (\~441 KB). Exposes `generate_document_parts()` which returns XML parts without ZIP assembly. Used with `@docxio/zip` for browser-optimized builds.

### docxio-napi[​](#docxio-napi "Direct link to docxio-napi")

Native Node.js binding via napi-rs. Exposes a `#[napi] generate()` function for maximum server-side performance without WASM overhead.

### docxio-cli[​](#docxio-cli "Direct link to docxio-cli")

Command-line tool built with `clap`:

* `docxio generate -i doc.json -o output.docx` -- generate from JSON
* `docxio patch template.docx data.json -o filled.docx` -- template patching
* `docxio watch -i doc.json -o output.docx` -- rebuild on file changes

### docxio-pdf[​](#docxio-pdf "Direct link to docxio-pdf")

PDF export via `printpdf`. Currently planned and not yet functional.

### docxio-bench[​](#docxio-bench "Direct link to docxio-bench")

Benchmarks using `criterion`. Measures XML generation, ZIP assembly, and end-to-end rendering performance.

### docxio-fuzz[​](#docxio-fuzz "Direct link to docxio-fuzz")

Fuzz testing targets for the document parser and renderer. Helps discover edge cases and potential panics.

## Workspace configuration[​](#workspace-configuration "Direct link to Workspace configuration")

All crates inherit workspace-level lints and formatting rules:

* `clippy.toml` + `[workspace.lints]` for consistent Clippy rules
* `rustfmt.toml` for formatting
* `unsafe_code = "deny"` across all crates
* `overflow-checks = true` in release builds


---

# Security

## Overview[​](#overview "Direct link to Overview")

docxio enforces security at multiple layers: Rust compiler guarantees, input validation, output sanitization, and CI auditing.

## No unsafe code[​](#no-unsafe-code "Direct link to No unsafe code")

`unsafe_code = "deny"` is enforced across all workspace crates. The Rust compiler rejects any `unsafe` blocks at compile time.

## Input validation[​](#input-validation "Direct link to Input validation")

Document trees are validated before processing:

| Limit             | Value   | Purpose                             |
| ----------------- | ------- | ----------------------------------- |
| Max sections      | 1,000   | Prevent excessive memory allocation |
| Max blocks        | 100,000 | Bound processing time               |
| Max nesting depth | 64      | Prevent stack overflow              |
| Max JSON size     | 50 MB   | Limit WASM memory usage             |

Attribute values (colors, sizes, dimensions, spacing, borders) are validated and clamped to OOXML spec-compliant ranges by the `docxio-ooxml::sanitize` module.

## XML escaping[​](#xml-escaping "Direct link to XML escaping")

All user-provided text is escaped via `quick-xml` before embedding in OOXML. docxio never uses string concatenation to build XML -- all XML is produced through the `quick-xml` Writer API.

## ZIP safety[​](#zip-safety "Direct link to ZIP safety")

When processing template `.docx` files:

* **Compressed input size limit**: 20 MB
* **Total uncompressed size limit**: 200 MB
* **Path traversal validation**: ZIP entry paths are checked for `..` and absolute path attacks
* **Entry count limits**: Prevents zip bomb attacks

## OOXML sanitization[​](#ooxml-sanitization "Direct link to OOXML sanitization")

The `sanitize` module in `docxio-ooxml` validates and clamps:

* **Colors**: Must be valid 6-character hex or named colors
* **Font sizes**: Clamped to valid half-point ranges
* **Dimensions**: Twip and EMU values bounded to prevent overflow
* **Spacing**: Before/after/line values clamped to spec limits
* **Border values**: Style, size, and color validated

## Dependency auditing[​](#dependency-auditing "Direct link to Dependency auditing")

CI runs on every push:

* `cargo audit` -- checks for known vulnerabilities in Rust dependencies
* `cargo deny check` -- enforces license compliance and blocks banned crates
* GitHub Actions pinned to commit SHAs to prevent supply chain attacks

## Overflow protection[​](#overflow-protection "Direct link to Overflow protection")

`overflow-checks = true` is enabled in release builds. Arithmetic overflow panics instead of wrapping silently.

## Known limitations[​](#known-limitations "Direct link to Known limitations")

* PDF export is not yet functional and should not be used in production
* Template patching with structured slots performs lightweight XML serialization outside the WASM boundary. For maximum safety, prefer the full WASM render path
* The WASM boundary serializes the full document tree as JSON. Extremely large documents (>50 MB JSON) may cause memory issues in the WASM runtime

## Reporting vulnerabilities[​](#reporting-vulnerabilities "Direct link to Reporting vulnerabilities")

If you discover a security vulnerability, please report it responsibly. **Do not open a public issue.** Instead, email the maintainers directly or use GitHub's private vulnerability reporting feature.


---

# Contributing

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* [Rust](https://rustup.rs/) (latest stable)
* [Node.js](https://nodejs.org/) 18+
* [pnpm](https://pnpm.io/) (monorepo package manager)
* [wasm-pack](https://rustwasm.github.io/wasm-pack/) (for building WASM modules)

## Setup[​](#setup "Direct link to Setup")

```
git clone https://github.com/your-org/docxio.git
cd docxio
pnpm install
```

## Development commands[​](#development-commands "Direct link to Development commands")

### Rust[​](#rust "Direct link to Rust")

```
# Type check all crates (excludes WASM/napi which need special toolchains)
cargo check --workspace --exclude docxio-wasm --exclude docxio-wasm-minimal --exclude docxio-napi

# Run all Rust tests
cargo test --workspace --exclude docxio-wasm --exclude docxio-wasm-minimal --exclude docxio-napi

# Lint with Clippy (warnings are errors)
cargo clippy --workspace --exclude docxio-wasm --exclude docxio-wasm-minimal --exclude docxio-napi -- -D warnings

# Check formatting
cargo fmt --all -- --check

# Auto-format
cargo fmt --all
```

### TypeScript[​](#typescript "Direct link to TypeScript")

```
# Type check TypeScript packages
pnpm turbo run typecheck

# Run TypeScript tests
pnpm turbo run test

# Run tests for a specific package
cd packages/docxio && npx vitest run
```

### WASM builds[​](#wasm-builds "Direct link to WASM builds")

```
# Build minimal WASM (441 KB)
wasm-pack build crates/docxio-wasm-minimal --target web --release

# Build full WASM (920 KB)
wasm-pack build crates/docxio-wasm --target web --release
```

### Benchmarks[​](#benchmarks "Direct link to Benchmarks")

```
cargo bench -p docxio-bench
```

### Security checks[​](#security-checks "Direct link to Security checks")

```
cargo audit
cargo deny check
```

## Testing conventions[​](#testing-conventions "Direct link to Testing conventions")

* **Rust**: Use [insta](https://insta.rs/) snapshot tests for XML output. Snapshots live alongside test files.
* **TypeScript**: Use [vitest](https://vitest.dev/) for unit tests in `packages/docxio/src/__tests__/`.
* Run `cargo insta review` to approve new or changed snapshots.

## Code style[​](#code-style "Direct link to Code style")

* **Rust**: `rustfmt.toml` enforces formatting. Run `cargo fmt --all` before committing.
* **Rust**: All types use `serde(rename_all = "camelCase")` for JS interop.
* **Rust**: XML is generated via the `quick-xml` Writer API -- never string concatenation.
* **TypeScript**: ESM-only (`"type": "module"`), `.js` extensions in imports, `strict: true`.
* **TypeScript**: Lowercase JSX element names map to OOXML types (e.g., `<paragraph>` maps to `w:p`).

## Project structure[​](#project-structure "Direct link to Project structure")

```
docxio/
├── crates/              # Rust workspace crates
│   ├── docxio-types/    # Shared type definitions
│   ├── docxio-ooxml/    # XML generation
│   ├── docxio-core/     # Orchestration (tree → XML → ZIP)
│   ├── docxio-wasm/     # Full WASM binding
│   ├── docxio-wasm-minimal/  # Minimal WASM binding
│   ├── docxio-napi/     # Node.js native binding
│   ├── docxio-cli/      # CLI tool
│   ├── docxio-pdf/      # PDF export (planned)
│   ├── docxio-bench/    # Benchmarks
│   └── docxio-fuzz/     # Fuzz testing
├── packages/
│   ├── docxio/          # Main TypeScript package
│   ├── @docxio/html/    # HTML/Markdown export
│   ├── @docxio/zip/     # JS ZIP assembly
│   ├── @docxio/bun/     # Bun build plugin
│   └── @docxio/node/    # Native Node.js binding
└── apps/
    └── docs/            # Docusaurus documentation site
```

## CI pipeline[​](#ci-pipeline "Direct link to CI pipeline")

Pull requests run:

1. `cargo check` + `cargo clippy` + `cargo fmt --check`
2. `cargo test` (Rust unit + snapshot tests)
3. `pnpm turbo run typecheck` + `pnpm turbo run test` (TypeScript)
4. `cargo audit` + `cargo deny check` (security)
5. WASM build verification


---

# Configuration

## Backend options[​](#backend-options "Direct link to Backend options")

Pass a `backend` option to `render` to control which WASM module is used:

```
import { render } from "docxio";

// Use the minimal 441 KB WASM (browser-optimized)
const bytes = await render(doc, { backend: "minimal" });

// Use the full 920 KB WASM (includes template engine, validator)
const bytes = await render(doc, { backend: "full" });

// Auto-detect (default) -- tries minimal, falls back to full
const bytes = await render(doc);
```

The `"minimal"` backend generates XML parts inside WASM and assembles the ZIP archive in JavaScript via `@docxio/zip`. The `"full"` backend does everything in Rust, including ZIP packaging, template patching, and validation.

## Pre-initializing WASM[​](#pre-initializing-wasm "Direct link to Pre-initializing WASM")

By default, the WASM module is initialized lazily on the first `render` call. To avoid the cold-start delay, call `initWasm()` early:

```
import { initWasm } from "docxio";

// Call once at app startup
await initWasm();
```

This is useful in server environments where you want the first request to be fast.

## Document metadata[​](#document-metadata "Direct link to Document metadata")

Set metadata on the `<document>` root element:

```
<document
  creator="Jane Doe"
  title="Q4 Report"
  description="Quarterly financial report"
  keywords="finance, report, Q4"
>
  ...
</document>
```

These values are written to the `docProps/core.xml` part of the `.docx` file.

## Default styles[​](#default-styles "Direct link to Default styles")

By default, docxio includes a base set of Word styles (Normal, Heading1-6, etc.). To disable them:

```
<document useDefaultStyles={false}>
  ...
</document>
```

You can also provide custom style definitions:

```
<document styles={{
  paragraphStyles: [
    {
      id: "CustomBody",
      name: "Custom Body",
      basedOn: "Normal",
      spacing: { after: 200, line: 276, lineRule: "auto" },
      runProps: { fontSize: 22, fontFamily: "Georgia" },
    },
  ],
}}>
  <section>
    <paragraph style="CustomBody"><run>Styled paragraph</run></paragraph>
  </section>
</document>
```

## Themes[​](#themes "Direct link to Themes")

Apply a built-in theme for consistent document-wide styling:

```
import { corporate } from "docxio";

<document theme={corporate}>
  ...
</document>
```

See [Styles and Themes](/docs/guides/styles-and-themes.md) for details on built-in themes and creating custom ones.

## WASM tree limits[​](#wasm-tree-limits "Direct link to WASM tree limits")

The WASM boundary enforces safety limits on the document tree:

| Limit             | Value   |
| ----------------- | ------- |
| Max sections      | 1,000   |
| Max blocks        | 100,000 |
| Max nesting depth | 64      |
| Max JSON size     | 50 MB   |

These limits prevent runaway memory usage in browser environments. Documents exceeding these limits will produce an error at render time.


---

# Installation

## Install the package[​](#install-the-package "Direct link to Install the package")

```
npm install docxio
# or
bun add docxio
```

## Configure TypeScript[​](#configure-typescript "Direct link to Configure TypeScript")

Add the JSX import source to your `tsconfig.json`:

```
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "docxio"
  }
}
```

This tells TypeScript to use docxio's JSX factory instead of React's. No React dependency is needed.

## Backend selection[​](#backend-selection "Direct link to Backend selection")

docxio ships with three WASM backends. The default `"auto"` mode works for most projects.

| Backend            | WASM Size | ZIP handling            | Best for                                              |
| ------------------ | --------- | ----------------------- | ----------------------------------------------------- |
| `"minimal"`        | 441 KB    | JS-side (`@docxio/zip`) | Browser -- smallest bundle                            |
| `"full"`           | 920 KB    | Rust-side               | Server -- includes parser, template engine, validator |
| `"auto"` (default) | --        | --                      | Tries minimal first, falls back to full               |

To force a specific backend:

```
import { render } from "docxio";

const bytes = await render(doc, { backend: "minimal" });
```

## Optional packages[​](#optional-packages "Direct link to Optional packages")

Install additional packages depending on your use case:

| Package                | Purpose                                        |
| ---------------------- | ---------------------------------------------- |
| `@docxio/html`         | HTML and Markdown export                       |
| `@docxio/bun`          | Bun build plugin                               |
| `@docxio/node`         | Native Node.js bindings via napi-rs            |
| `@docxio/zip`          | JS-side ZIP assembly (used by minimal backend) |
| `@docxio/wasm-minimal` | Minimal WASM binary (XML only)                 |

```
# Example: add HTML export
npm install @docxio/html
```

## Verify installation[​](#verify-installation "Direct link to Verify installation")

Create a file called `hello.tsx` and run it:

```
/** @jsxImportSource docxio */
import { render } from "docxio";

const doc = (
  <document title="Test">
    <section>
      <paragraph><run>It works!</run></paragraph>
    </section>
  </document>
);

const bytes = await render(doc);
console.log(`Generated ${bytes.length} bytes`);
```


---

# Quick Start

## Minimal example[​](#minimal-example "Direct link to Minimal example")

Every docxio document starts with a `<document>` root containing one or more `<section>` elements. Sections hold paragraphs, tables, and other block-level content.

```
/** @jsxImportSource docxio */
import { render } from "docxio";

const doc = (
  <document title="Hello">
    <section>
      <paragraph><run bold>Hello, World!</run></paragraph>
    </section>
  </document>
);

const bytes = await render(doc);
```

The `render` function returns a `Uint8Array` containing the `.docx` file bytes.

## Write to a file[​](#write-to-a-file "Direct link to Write to a file")

### Bun[​](#bun "Direct link to Bun")

```
await Bun.write("hello.docx", bytes);
```

### Node.js[​](#nodejs "Direct link to Node.js")

```
import { renderToFile } from "docxio";

await renderToFile(doc, "hello.docx");
```

Or use the buffer helper:

```
import { renderToBuffer } from "docxio";
import { writeFileSync } from "node:fs";

const buf = await renderToBuffer(doc);
writeFileSync("hello.docx", buf);
```

## Render to a Blob (browser)[​](#render-to-a-blob-browser "Direct link to Render to a Blob (browser)")

```
import { renderToBlob } from "docxio";

const blob = await renderToBlob(doc);
const url = URL.createObjectURL(blob);
// Trigger download via an <a> element
```

## Render to base64[​](#render-to-base64 "Direct link to Render to base64")

```
import { renderToBase64 } from "docxio";

const base64 = await renderToBase64(doc);
```

## Adding structure[​](#adding-structure "Direct link to Adding structure")

A more complete example with headings, styled text, and a table:

```
/** @jsxImportSource docxio */
import { render } from "docxio";

const doc = (
  <document creator="docxio" title="Report">
    <section>
      <heading level={1}><run>Quarterly Report</run></heading>
      <paragraph>
        <run>Revenue increased by </run>
        <run bold color="2E74B5">15%</run>
        <run> this quarter.</run>
      </paragraph>
      <table borders="single" width={7500}>
        <row>
          <cell shading={{ fill: "D9E1F2" }}>
            <paragraph><run bold>Metric</run></paragraph>
          </cell>
          <cell shading={{ fill: "D9E1F2" }}>
            <paragraph><run bold>Value</run></paragraph>
          </cell>
        </row>
        <row>
          <cell><paragraph><run>Revenue</run></paragraph></cell>
          <cell><paragraph><run>$1.2M</run></paragraph></cell>
        </row>
      </table>
    </section>
  </document>
);

const bytes = await render(doc);
```

## Next steps[​](#next-steps "Direct link to Next steps")

* [Configuration](/docs/getting-started/configuration.md) -- backend options, WASM initialization, strict mode
* [Paragraphs and Formatting](/docs/guides/paragraphs-and-formatting.md) -- text styling in depth
* [Components reference](/docs/api/components.md) -- all available JSX elements


---

# Data Components

docxio provides higher-level components that wrap common document patterns. Import them from the main package:

```
import { DataTable, PageNumbers, Watermark, Signature, TotalRow, Divider, Spacer } from "docxio";
```

## DataTable[​](#datatable "Direct link to DataTable")

Generates a formatted table from an array of data objects:

```
<DataTable
  columns={[
    { key: "name", label: "Name" },
    { key: "department", label: "Department" },
    { key: "amount", label: "Amount", alignment: "right" },
  ]}
  data={[
    { name: "Alice", department: "Engineering", amount: "$100,000" },
    { name: "Bob", department: "Marketing", amount: "$85,000" },
    { name: "Carol", department: "Engineering", amount: "$95,000" },
  ]}
  zebra
/>
```

The `zebra` prop adds alternating row shading. DataTable automatically creates a header row with bold text.

## PageNumbers[​](#pagenumbers "Direct link to PageNumbers")

Inserts a page number field, typically used in footers:

```
<footer>
  <PageNumbers />
</footer>
```

Renders as "Page X of Y" using OOXML field codes.

## Watermark[​](#watermark "Direct link to Watermark")

Adds a large, centered, rotated text watermark:

```
<Watermark text="DRAFT" />
<Watermark text="CONFIDENTIAL" />
```

## Signature[​](#signature "Direct link to Signature")

Creates a signature block with a line and name:

```
<Signature name="Jane Doe" title="CEO" date="2025-12-31" />
```

## TotalRow[​](#totalrow "Direct link to TotalRow")

A right-aligned summary line, useful at the bottom of financial tables:

```
<TotalRow label="Total Revenue" value="$280,000" />
```

## Divider[​](#divider "Direct link to Divider")

A horizontal rule implemented as a bordered paragraph:

```
<paragraph><run>Section One</run></paragraph>
<Divider />
<paragraph><run>Section Two</run></paragraph>
```

## Spacer[​](#spacer "Direct link to Spacer")

An empty paragraph with configurable height, useful for visual spacing:

```
<Spacer height={480} />
```

The `height` is in twips (1/20 of a point). `480 twips = 24pt = ~1/3 inch`.

## Combining data components[​](#combining-data-components "Direct link to Combining data components")

```
<document title="Invoice">
  <section>
    <heading level={1}><run>Invoice #1234</run></heading>

    <DataTable
      columns={[
        { key: "item", label: "Item" },
        { key: "qty", label: "Qty", alignment: "right" },
        { key: "price", label: "Price", alignment: "right" },
      ]}
      data={lineItems}
      zebra
    />

    <Spacer height={240} />
    <TotalRow label="Total" value="$1,500.00" />
    <Divider />

    <Spacer height={480} />
    <Signature name="Jane Doe" title="Accounts Payable" />

    <footer>
      <PageNumbers />
    </footer>
  </section>
</document>
```


---

# Headers and Footers

## Basic usage[​](#basic-usage "Direct link to Basic usage")

Add `<header>` and `<footer>` elements inside a `<section>`:

```
<section>
  <header>
    <paragraph alignment="right">
      <run fontSize={18} color="595959">Company Name</run>
    </paragraph>
  </header>

  <paragraph><run>Document body content.</run></paragraph>

  <footer>
    <paragraph alignment="center">
      <run fontSize={16} color="595959">Page </run>
      <field code="PAGE" />
      <run fontSize={16} color="595959"> of </run>
      <field code="NUMPAGES" />
    </paragraph>
  </footer>
</section>
```

## Header/footer types[​](#headerfooter-types "Direct link to Header/footer types")

Each section can have up to three header and three footer variants:

| Type        | When displayed                              |
| ----------- | ------------------------------------------- |
| `"default"` | All pages (unless overridden by first/even) |
| `"first"`   | First page of the section only              |
| `"even"`    | Even-numbered pages only                    |

```
<section>
  <header type="default">
    <paragraph><run>Default Header</run></paragraph>
  </header>
  <header type="first">
    <paragraph><run>First Page Header</run></paragraph>
  </header>
  <header type="even">
    <paragraph><run>Even Page Header</run></paragraph>
  </header>

  {/* ... body content ... */}
</section>
```

## Page numbers in footers[​](#page-numbers-in-footers "Direct link to Page numbers in footers")

Use the `<field>` element to insert dynamic page numbers:

```
<footer>
  <paragraph alignment="center">
    <field code="PAGE" />
    <run> / </run>
    <field code="NUMPAGES" />
  </paragraph>
</footer>
```

Available field codes: `PAGE` (current page), `NUMPAGES` (total pages), `DATE` (current date).

## Headers with images[​](#headers-with-images "Direct link to Headers with images")

```
<header>
  <paragraph>
    <image src={logoDataUri} widthPt={48} heightPt={48} altText="Logo" />
    <run fontSize={24} bold> Company Report</run>
  </paragraph>
</header>
```

## Per-section headers[​](#per-section-headers "Direct link to Per-section headers")

Each `<section>` can define its own headers and footers independently. This is useful for documents with a cover page followed by different content sections:

```
<document>
  {/* Cover page with no header */}
  <section>
    <heading level={1}><run>Annual Report 2025</run></heading>
  </section>

  {/* Main content with header and footer */}
  <section>
    <header>
      <paragraph alignment="right"><run>Annual Report 2025</run></paragraph>
    </header>
    <paragraph><run>Chapter 1 content...</run></paragraph>
    <footer>
      <paragraph alignment="center"><field code="PAGE" /></paragraph>
    </footer>
  </section>
</document>
```


---

# HTML and Markdown Export

The `@docxio/html` package converts docxio document trees to HTML or Markdown strings. This is useful for previews, email bodies, or static site content.

## Installation[​](#installation "Direct link to Installation")

```
npm install @docxio/html
```

## Render to HTML[​](#render-to-html "Direct link to Render to HTML")

```
/** @jsxImportSource docxio */
import { renderToHtml } from "@docxio/html";

const doc = (
  <document>
    <section>
      <heading level={1}><run>Title</run></heading>
      <paragraph>
        <run>Regular text with </run>
        <run bold>bold</run>
        <run> and </run>
        <run italic>italic</run>
      </paragraph>
      <table>
        <row>
          <cell><paragraph><run>A</run></paragraph></cell>
          <cell><paragraph><run>B</run></paragraph></cell>
        </row>
      </table>
    </section>
  </document>
);

const html = renderToHtml(doc);
```

Output:

```
<h1>Title</h1>
<p>Regular text with <strong>bold</strong> and <em>italic</em></p>
<table><tr><td>A</td><td>B</td></tr></table>
```

## Render to Markdown[​](#render-to-markdown "Direct link to Render to Markdown")

```
import { renderToMarkdown } from "@docxio/html";

const markdown = renderToMarkdown(doc);
```

Output:

```
# Title

Regular text with **bold** and *italic*

| A | B |
|---|---|
```

## Element mapping[​](#element-mapping "Direct link to Element mapping")

| docxio element        | HTML output | Markdown output      |
| --------------------- | ----------- | -------------------- |
| `<heading level={N}>` | `<hN>`      | `# `to `######`      |
| `<paragraph>`         | `<p>`       | Plain text + newline |
| `<run bold>`          | `<strong>`  | `**text**`           |
| `<run italic>`        | `<em>`      | `*text*`             |
| `<run underline>`     | `<u>`       | Plain text           |
| `<table>`             | `<table>`   | Pipe table           |
| `<hyperlink>`         | `<a href>`  | `[text](url)`        |
| `<image>`             | `<img>`     | `![alt](src)`        |
| `<bullet-list>`       | `<ul>`      | `- item`             |
| `<numbered-list>`     | `<ol>`      | `1. item`            |

## Use cases[​](#use-cases "Direct link to Use cases")

* **Email previews** -- convert a docxio document to HTML for email body content
* **Static site generation** -- export document content as Markdown for CMS integration
* **Testing** -- compare HTML output in snapshot tests for easier visual diffing

See also the [render API reference](/docs/api/render.md) for all render function signatures.


---

# Images

## Inline images[​](#inline-images "Direct link to Inline images")

Images are inline by default and flow with the text:

```
<paragraph>
  <image src="data:image/png;base64,iVBOR..." width={914400} height={914400} />
</paragraph>
```

Dimensions are specified in EMUs (English Metric Units). `914400 EMU = 1 inch`.

### Convenience size props[​](#convenience-size-props "Direct link to Convenience size props")

Use `widthPt` and `heightPt` for point-based sizing:

```
<image src="data:image/png;base64,..." widthPt={144} heightPt={144} />
```

## Data URIs[​](#data-uris "Direct link to Data URIs")

The `src` prop accepts base64-encoded data URIs:

```
import { readFileSync } from "node:fs";

const imageData = readFileSync("logo.png");
const base64 = imageData.toString("base64");
const src = `data:image/png;base64,${base64}`;

<image src={src} widthPt={72} heightPt={72} altText="Company logo" />
```

## Supported formats[​](#supported-formats "Direct link to Supported formats")

| Format | `format` value |
| ------ | -------------- |
| PNG    | `"png"`        |
| JPEG   | `"jpeg"`       |
| GIF    | `"gif"`        |
| BMP    | `"bmp"`        |
| SVG    | `"svg"`        |

The format is typically auto-detected from the data URI MIME type. Use the `format` prop to specify it explicitly if needed.

## Floating images[​](#floating-images "Direct link to Floating images")

Set `floating` to position the image relative to the page:

```
<image
  src={src}
  widthPt={200}
  heightPt={150}
  floating
  wrapText="square"
  floatPosition={{
    horizontalPosition: {
      relative: "column",
      offset: 457200, // EMUs from left
    },
    verticalPosition: {
      relative: "paragraph",
      offset: 0,
    },
  }}
/>
```

### Wrap modes[​](#wrap-modes "Direct link to Wrap modes")

| Value            | Description                                |
| ---------------- | ------------------------------------------ |
| `"square"`       | Text wraps in a rectangle around the image |
| `"tight"`        | Text wraps tightly to the image shape      |
| `"through"`      | Text flows through transparent areas       |
| `"topAndBottom"` | Text above and below only                  |
| `"behind"`       | Image behind text                          |
| `"inFront"`      | Image in front of text                     |

## Image props reference[​](#image-props-reference "Direct link to Image props reference")

| Prop            | Type               | Description                         |
| --------------- | ------------------ | ----------------------------------- |
| `src`           | `string`           | **Required.** Data URI or file path |
| `width`         | `number`           | Width in EMUs                       |
| `height`        | `number`           | Height in EMUs                      |
| `widthPt`       | `number`           | Width in points                     |
| `heightPt`      | `number`           | Height in points                    |
| `altText`       | `string`           | Accessibility alt text              |
| `floating`      | `boolean`          | Enable floating layout              |
| `wrapText`      | `WrapText`         | Text wrapping mode                  |
| `floatPosition` | `FloatingPosition` | Positioning details                 |
| `format`        | `string`           | Image format hint                   |


---

# Lists

## Bullet lists[​](#bullet-lists "Direct link to Bullet lists")

```
<bullet-list>
  <list-item><paragraph><run>First item</run></paragraph></list-item>
  <list-item><paragraph><run>Second item</run></paragraph></list-item>
  <list-item><paragraph><run>Third item</run></paragraph></list-item>
</bullet-list>
```

## Numbered lists[​](#numbered-lists "Direct link to Numbered lists")

```
<numbered-list>
  <list-item><paragraph><run>Step one</run></paragraph></list-item>
  <list-item><paragraph><run>Step two</run></paragraph></list-item>
  <list-item><paragraph><run>Step three</run></paragraph></list-item>
</numbered-list>
```

### Numbering formats[​](#numbering-formats "Direct link to Numbering formats")

The `format` prop on `<numbered-list>` controls the numbering style:

| Format                | Example    |
| --------------------- | ---------- |
| `"decimal"` (default) | 1, 2, 3    |
| `"lowerRoman"`        | i, ii, iii |
| `"upperRoman"`        | I, II, III |
| `"lowerLetter"`       | a, b, c    |
| `"upperLetter"`       | A, B, C    |

```
<numbered-list format="lowerRoman">
  <list-item><paragraph><run>First</run></paragraph></list-item>
  <list-item><paragraph><run>Second</run></paragraph></list-item>
</numbered-list>
```

### Custom start number[​](#custom-start-number "Direct link to Custom start number")

```
<numbered-list start={5}>
  <list-item><paragraph><run>Starts at five</run></paragraph></list-item>
  <list-item><paragraph><run>Six</run></paragraph></list-item>
</numbered-list>
```

## Nested lists[​](#nested-lists "Direct link to Nested lists")

Use the `level` prop on `<list-item>` to create nested lists:

```
<bullet-list>
  <list-item level={0}><paragraph><run>Top level</run></paragraph></list-item>
  <list-item level={1}><paragraph><run>Nested item</run></paragraph></list-item>
  <list-item level={1}><paragraph><run>Another nested</run></paragraph></list-item>
  <list-item level={0}><paragraph><run>Back to top</run></paragraph></list-item>
</bullet-list>
```

Levels are 0-indexed and support up to 9 levels of nesting (0-8).

## Dynamic lists[​](#dynamic-lists "Direct link to Dynamic lists")

```
const items = ["Apples", "Bananas", "Cherries"];

<bullet-list>
  {items.map((item) => (
    <list-item key={item}>
      <paragraph><run>{item}</run></paragraph>
    </list-item>
  ))}
</bullet-list>
```

## List item props[​](#list-item-props "Direct link to List item props")

| Prop        | Type             | Description                    |
| ----------- | ---------------- | ------------------------------ |
| `level`     | `number`         | Nesting level (0-8, default 0) |
| `numbering` | `NumberingProps` | Override numbering reference   |

## Numbered list props[​](#numbered-list-props "Direct link to Numbered list props")

| Prop        | Type              | Description                |
| ----------- | ----------------- | -------------------------- |
| `format`    | `NumberingFormat` | Numbering style            |
| `start`     | `number`          | Starting number            |
| `reference` | `string`          | Named numbering definition |

## Bullet list props[​](#bullet-list-props "Direct link to Bullet list props")

| Prop        | Type     | Description                |
| ----------- | -------- | -------------------------- |
| `reference` | `string` | Named numbering definition |


---

# Paragraphs and Formatting

## Basic paragraphs[​](#basic-paragraphs "Direct link to Basic paragraphs")

A `<paragraph>` wraps one or more `<run>` elements. Each run is a contiguous span of text with the same formatting.

```
<paragraph>
  <run>This is a simple paragraph.</run>
</paragraph>
```

## Paragraph alignment and spacing[​](#paragraph-alignment-and-spacing "Direct link to Paragraph alignment and spacing")

```
<paragraph alignment="center" spacing={{ before: 240, after: 120 }}>
  <run>Centered with spacing</run>
</paragraph>

<paragraph alignment="justify" indentation={{ left: 720, firstLine: 360 }}>
  <run>Justified text with left indent and first-line indent.</run>
</paragraph>
```

**Alignment values:** `"left"`, `"center"`, `"right"`, `"justify"`, `"start"`, `"end"`, `"both"`.

## Run formatting[​](#run-formatting "Direct link to Run formatting")

Runs support rich formatting through boolean flags and value props:

```
<paragraph>
  <run bold>Bold text</run>
  <run italic>Italic text</run>
  <run bold italic>Bold and italic</run>
  <run underline="single">Underlined</run>
  <run strike>Strikethrough</run>
  <run fontSize={28} fontFamily="Georgia" color="2E74B5">
    Custom font, size, and color
  </run>
</paragraph>
```

### All run props[​](#all-run-props "Direct link to All run props")

| Prop               | Type                        | Description                                          |
| ------------------ | --------------------------- | ---------------------------------------------------- |
| `bold`             | `boolean`                   | Bold text                                            |
| `italic`           | `boolean`                   | Italic text                                          |
| `underline`        | `UnderlineStyle \| boolean` | Underline (e.g., `"single"`, `"double"`, `"dotted"`) |
| `strike`           | `boolean`                   | Strikethrough                                        |
| `doubleStrike`     | `boolean`                   | Double strikethrough                                 |
| `fontSize`         | `number`                    | Font size in half-points (24 = 12pt)                 |
| `fontFamily`       | `string`                    | Font name (e.g., `"Calibri"`)                        |
| `color`            | `string`                    | Hex color without `#` (e.g., `"FF0000"`)             |
| `highlight`        | `HighlightColor`            | Background highlight color                           |
| `superscript`      | `boolean`                   | Superscript                                          |
| `subscript`        | `boolean`                   | Subscript                                            |
| `allCaps`          | `boolean`                   | All capitals                                         |
| `smallCaps`        | `boolean`                   | Small capitals                                       |
| `characterSpacing` | `number`                    | Spacing adjustment in twips                          |

## Headings[​](#headings "Direct link to Headings")

Use the `<heading>` element for structured headings:

```
<heading level={1}><run>Chapter Title</run></heading>
<heading level={2}><run>Section Title</run></heading>
```

Or apply heading styles to paragraphs:

```
<paragraph style="Heading1"><run>Chapter Title</run></paragraph>
```

## Paragraph styles[​](#paragraph-styles "Direct link to Paragraph styles")

Reference named styles defined in the document or built-in Word styles:

```
<document styles={{
  paragraphStyles: [{
    id: "Quote",
    name: "Quote",
    alignment: "center",
    spacing: { before: 200, after: 200 },
    runProps: { italic: true, color: "595959" },
  }],
}}>
  <section>
    <paragraph style="Quote"><run>A styled quote.</run></paragraph>
  </section>
</document>
```

## Breaks[​](#breaks "Direct link to Breaks")

Insert page, line, or column breaks:

```
<paragraph><run>Before the break</run></paragraph>
<pagebreak />
<paragraph><run>On a new page</run></paragraph>

<paragraph>
  <run>Line one</run>
  <linebreak />
  <run>Line two</run>
</paragraph>
```

## Tabs[​](#tabs "Direct link to Tabs")

```
<paragraph>
  <run>Name</run>
  <tab />
  <run>Value</run>
</paragraph>
```


---

# Streaming

## Overview[​](#overview "Direct link to Overview")

docxio supports streaming `.docx` bytes as a `ReadableStream`, which is useful for HTTP responses where you want to start sending data before the entire document is assembled.

## renderToStream[​](#rendertostream "Direct link to renderToStream")

```
import { renderToStream } from "docxio";

const stream = renderToStream(
  <document title="Streamed Report">
    <section>
      <paragraph><run>Hello from a stream!</run></paragraph>
    </section>
  </document>
);
```

The returned stream is a standard web `ReadableStream<Uint8Array>`.

## HTTP response (Bun)[​](#http-response-bun "Direct link to HTTP response (Bun)")

```
import { renderToStream } from "docxio";

Bun.serve({
  fetch(req) {
    const doc = (
      <document title="Report">
        <section>
          <paragraph><run>Generated on the fly.</run></paragraph>
        </section>
      </document>
    );

    const stream = renderToStream(doc);

    return new Response(stream, {
      headers: {
        "Content-Type":
          "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        "Content-Disposition": 'attachment; filename="report.docx"',
      },
    });
  },
});
```

## HTTP response (Node.js / Express)[​](#http-response-nodejs--express "Direct link to HTTP response (Node.js / Express)")

```
import { renderToReadableStream } from "docxio";
import { Readable } from "node:stream";

app.get("/report.docx", async (req, res) => {
  const doc = (
    <document title="Report">
      <section>
        <paragraph><run>Server-generated document.</run></paragraph>
      </section>
    </document>
  );

  const webStream = renderToReadableStream(doc);
  const nodeStream = Readable.fromWeb(webStream);

  res.setHeader(
    "Content-Type",
    "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
  );
  res.setHeader("Content-Disposition", 'attachment; filename="report.docx"');
  nodeStream.pipe(res);
});
```

## When to use streaming[​](#when-to-use-streaming "Direct link to When to use streaming")

Streaming is beneficial when:

* The document is large and you want to reduce time-to-first-byte
* You are serving documents over HTTP and want to avoid buffering the entire file in memory
* You are piping directly to a file or another stream consumer

For small documents or when you need the complete bytes (e.g., to calculate a hash), use `render()` instead.


---

# Styles and Themes

## Paragraph styles[​](#paragraph-styles "Direct link to Paragraph styles")

Define reusable paragraph styles in the `<document>` element:

```
<document styles={{
  paragraphStyles: [
    {
      id: "BodyText",
      name: "Body Text",
      basedOn: "Normal",
      spacing: { after: 200, line: 276, lineRule: "auto" },
      runProps: { fontSize: 22, fontFamily: "Calibri" },
    },
    {
      id: "Quote",
      name: "Quote",
      basedOn: "Normal",
      alignment: "center",
      indentation: { left: 720, right: 720 },
      runProps: { italic: true, color: "595959" },
    },
  ],
}}>
  <section>
    <paragraph style="BodyText"><run>Regular body text.</run></paragraph>
    <paragraph style="Quote"><run>An indented, italic quote.</run></paragraph>
  </section>
</document>
```

## Character styles[​](#character-styles "Direct link to Character styles")

Character styles apply to runs without affecting paragraph layout:

```
<document styles={{
  characterStyles: [
    {
      id: "Emphasis",
      name: "Emphasis",
      italic: true,
      color: "2E74B5",
    },
  ],
}}>
  <section>
    <paragraph>
      <run>Normal text and </run>
      <run style="Emphasis">emphasized text</run>
    </paragraph>
  </section>
</document>
```

## Built-in themes[​](#built-in-themes "Direct link to Built-in themes")

docxio ships with three themes that set fonts, colors, heading styles, and page margins:

```
import { corporate, academic, minimal } from "docxio";

<document theme={corporate}>...</document>
<document theme={academic}>...</document>
<document theme={minimal}>...</document>
```

| Theme       | Heading font    | Body font       | Primary color |
| ----------- | --------------- | --------------- | ------------- |
| `corporate` | Calibri         | Calibri         | `#1F4E79`     |
| `academic`  | Times New Roman | Times New Roman | (varies)      |
| `minimal`   | Helvetica       | Helvetica       | (varies)      |

## Custom themes[​](#custom-themes "Direct link to Custom themes")

Create a custom theme by implementing the `Theme` interface:

```
import type { Theme } from "docxio";

const myTheme: Theme = {
  name: "brand",
  fonts: {
    heading: "Inter",
    body: "Inter",
    mono: "JetBrains Mono",
  },
  colors: {
    primary: "6C3AE0",
    secondary: "9B6FE8",
    accent: "FF6B35",
    text: "1A1A1A",
    textLight: "6B7280",
    background: "FFFFFF",
  },
  headingStyles: {
    1: { fontSize: 36, bold: true, color: "6C3AE0", spacingBefore: 240, spacingAfter: 120 },
    2: { fontSize: 28, bold: true, color: "6C3AE0", spacingBefore: 200, spacingAfter: 100 },
    3: { fontSize: 24, bold: true, color: "9B6FE8", spacingBefore: 160, spacingAfter: 80 },
    4: { fontSize: 22, bold: true, color: "9B6FE8", spacingBefore: 120, spacingAfter: 60 },
    5: { fontSize: 20, bold: true, italic: true, color: "6B7280", spacingBefore: 100, spacingAfter: 40 },
    6: { fontSize: 20, italic: true, color: "6B7280", spacingBefore: 80, spacingAfter: 40 },
  },
  paragraph: {
    fontSize: 22,
    lineSpacing: 276,
    spacingAfter: 160,
  },
  table: {
    borderStyle: "single",
    borderColor: "6C3AE0",
    headerBackground: "6C3AE0",
    headerColor: "FFFFFF",
  },
  page: {
    marginTop: 1440,
    marginRight: 1440,
    marginBottom: 1440,
    marginLeft: 1440,
  },
};
```

## Theme interface reference[​](#theme-interface-reference "Direct link to Theme interface reference")

| Property            | Type                             | Description                                              |
| ------------------- | -------------------------------- | -------------------------------------------------------- |
| `name`              | `string`                         | Theme identifier                                         |
| `fonts.heading`     | `string`                         | Font for headings                                        |
| `fonts.body`        | `string`                         | Font for body text                                       |
| `fonts.mono`        | `string`                         | Font for monospace                                       |
| `colors.primary`    | `string`                         | Primary brand color (hex)                                |
| `colors.secondary`  | `string`                         | Secondary color                                          |
| `colors.accent`     | `string`                         | Accent color                                             |
| `colors.text`       | `string`                         | Default text color                                       |
| `colors.textLight`  | `string`                         | Light/muted text color                                   |
| `colors.background` | `string`                         | Background color                                         |
| `headingStyles`     | `Record<1-6, HeadingThemeStyle>` | Per-level heading styles                                 |
| `paragraph`         | `object`                         | Default paragraph font size, line spacing, spacing after |
| `table`             | `object`                         | Table border style/color, header background/color        |
| `page`              | `object`                         | Page margins (top, right, bottom, left) in twips         |


---

# Tables

## Basic table[​](#basic-table "Direct link to Basic table")

Tables consist of `<table>`, `<row>`, and `<cell>` elements. Every cell must contain at least one `<paragraph>`.

```
<table borders="single" width={7500}>
  <row>
    <cell width={3000}><paragraph><run bold>Name</run></paragraph></cell>
    <cell width={2000}><paragraph><run bold>Age</run></paragraph></cell>
  </row>
  <row>
    <cell><paragraph><run>Alice</run></paragraph></cell>
    <cell><paragraph><run>30</run></paragraph></cell>
  </row>
</table>
```

## Table props[​](#table-props "Direct link to Table props")

| Prop          | Type                                | Description                                                     |
| ------------- | ----------------------------------- | --------------------------------------------------------------- |
| `width`       | `string \| number`                  | Width in twips or percentage (`"100%"`)                         |
| `widthType`   | `"auto" \| "dxa" \| "pct" \| "nil"` | Width unit type                                                 |
| `borders`     | `Borders`                           | Border definitions (top, right, bottom, left, insideH, insideV) |
| `alignment`   | `Alignment`                         | Horizontal alignment of the table                               |
| `layout`      | `"fixed" \| "autofit"`              | Column width algorithm                                          |
| `style`       | `string`                            | Named table style                                               |
| `indent`      | `number`                            | Left margin indent in twips                                     |
| `cellMargins` | `object`                            | Default cell margins (top, right, bottom, left)                 |

## Row props[​](#row-props "Direct link to Row props")

| Prop         | Type                             | Description                            |
| ------------ | -------------------------------- | -------------------------------------- |
| `header`     | `boolean`                        | Repeat this row as header on each page |
| `height`     | `number`                         | Row height in twips                    |
| `heightRule` | `"auto" \| "atLeast" \| "exact"` | Height behavior                        |
| `cantSplit`  | `boolean`                        | Prevent row from breaking across pages |

## Cell props[​](#cell-props "Direct link to Cell props")

| Prop                | Type                            | Description                 |
| ------------------- | ------------------------------- | --------------------------- |
| `width`             | `number`                        | Cell width in twips         |
| `shading`           | `Shading`                       | Background fill and pattern |
| `columnSpan`        | `number`                        | Number of columns to span   |
| `verticalMerge`     | `"restart" \| "continue"`       | Vertical merge control      |
| `verticalAlignment` | `"top" \| "center" \| "bottom"` | Content alignment           |
| `borders`           | `Borders`                       | Per-cell border override    |

## Shading and header rows[​](#shading-and-header-rows "Direct link to Shading and header rows")

```
<table borders="single" width={9000}>
  <row header>
    <cell shading={{ fill: "1F4E79" }}>
      <paragraph><run bold color="FFFFFF">Header</run></paragraph>
    </cell>
  </row>
  <row>
    <cell shading={{ fill: "D9E1F2" }}>
      <paragraph><run>Shaded cell</run></paragraph>
    </cell>
  </row>
</table>
```

## Column spans[​](#column-spans "Direct link to Column spans")

```
<row>
  <cell columnSpan={2}>
    <paragraph><run>This cell spans two columns</run></paragraph>
  </cell>
</row>
```

## Vertical merge (row spans)[​](#vertical-merge-row-spans "Direct link to Vertical merge (row spans)")

```
<row>
  <cell verticalMerge="restart"><paragraph><run>Spans 2 rows</run></paragraph></cell>
  <cell><paragraph><run>Row 1</run></paragraph></cell>
</row>
<row>
  <cell verticalMerge="continue"><paragraph /></cell>
  <cell><paragraph><run>Row 2</run></paragraph></cell>
</row>
```

## Dynamic tables[​](#dynamic-tables "Direct link to Dynamic tables")

Use `.map()` to generate rows from data:

```
<table borders="single" width={7500}>
  <row header>
    <cell><paragraph><run bold>Name</run></paragraph></cell>
    <cell><paragraph><run bold>Amount</run></paragraph></cell>
  </row>
  {data.map((item) => (
    <row key={item.id}>
      <cell><paragraph><run>{item.name}</run></paragraph></cell>
      <cell><paragraph alignment="right"><run>{item.amount}</run></paragraph></cell>
    </row>
  ))}
</table>
```

For an even simpler API, see the [DataTable component](/docs/guides/data-components.md).


---

# Templates

docxio can load existing `.docx` files as templates and replace `{{placeholder}}` tokens with dynamic values.

## Loading a template[​](#loading-a-template "Direct link to Loading a template")

```
import { loadTemplate } from "docxio";

const templateBytes = await Bun.file("template.docx").bytes();
const tpl = await loadTemplate(templateBytes);

// Inspect available placeholder slots
console.log("Slots:", tpl.slots); // ["title", "author", "date", ...]
```

The `loadTemplate` function parses the `.docx` archive and scans for `{{placeholder}}` tokens in the document body. It returns a template object with a `slots` array listing all discovered placeholders.

## Simple text replacement[​](#simple-text-replacement "Direct link to Simple text replacement")

```
import { loadTemplate, fillTemplate } from "docxio";

const tpl = await loadTemplate(templateBytes);

const patchedBytes = await fillTemplate(tpl, {
  title: "Q4 Financial Report",
  author: "Jane Doe",
  date: "2025-12-31",
});

await Bun.write("filled.docx", patchedBytes);
```

String values replace the `{{placeholder}}` text inline, preserving the surrounding paragraph formatting.

## Structured slot filling[​](#structured-slot-filling "Direct link to Structured slot filling")

For rich content (tables, styled paragraphs, images), use the `<Template>` and `<Slot>` JSX components:

```
import { loadTemplate, render, Template, Slot } from "docxio";

const tpl = await loadTemplate(templateBytes);

const doc = (
  <Template src={tpl} values={{ title: "Q4 Report", author: "Jane Doe" }}>
    <Slot name="content">
      <paragraph alignment="center">
        <run bold fontSize={28}>Revenue Summary</run>
      </paragraph>
      <table borders="single" width={7500}>
        <row>
          <cell><paragraph><run bold>Metric</run></paragraph></cell>
          <cell><paragraph><run bold>Value</run></paragraph></cell>
        </row>
        <row>
          <cell><paragraph><run>Revenue</run></paragraph></cell>
          <cell><paragraph><run>$1.2M</run></paragraph></cell>
        </row>
      </table>
    </Slot>
  </Template>
);

const bytes = await render(doc);
```

When a `<Slot>` is used, the entire paragraph containing `{{content}}` is replaced with the rendered OOXML from the slot's children.

## Mixing text and slot values[​](#mixing-text-and-slot-values "Direct link to Mixing text and slot values")

You can combine simple string replacements (`values` prop) with structured `<Slot>` children:

```
<Template src={tpl} values={{ title: "Report", date: "2025-01-01" }}>
  <Slot name="summary">
    <paragraph><run bold>Executive Summary</run></paragraph>
    <paragraph><run>This quarter showed strong growth...</run></paragraph>
  </Slot>
</Template>
```

## Template API reference[​](#template-api-reference "Direct link to Template API reference")

| Export                      | Description                                                      |
| --------------------------- | ---------------------------------------------------------------- |
| `loadTemplate(bytes)`       | Parse `.docx` bytes, detect `{{slots}}`, return template object  |
| `fillTemplate(tpl, values)` | Replace slots with string values, return patched `.docx` bytes   |
| `Template`                  | JSX component for template-based rendering with `<Slot>` support |
| `Slot`                      | JSX component for injecting structured content into a named slot |

### SlotValue type[​](#slotvalue-type "Direct link to SlotValue type")

Slot values can be either strings (for simple text replacement) or `DocumentNode` trees (for structured content):

```
type SlotValue = string | DocumentNode;
```


---

# @docxio/bun

Bun build plugin for docxio. Handles WASM file resolution and JSX configuration during `bun build`.

## Installation[​](#installation "Direct link to Installation")

```
bun add @docxio/bun
```

**Size:** \~2 KB

## Usage[​](#usage "Direct link to Usage")

Register the plugin in your Bun build script:

```
import { docxioPlugin } from "@docxio/bun";

await Bun.build({
  entrypoints: ["./src/index.tsx"],
  outdir: "./dist",
  plugins: [docxioPlugin()],
});
```

The plugin:

1. Resolves the docxio WASM binary so Bun can bundle it correctly
2. Configures the JSX transform to use `docxio` as the import source
3. Ensures `.wasm` files are included in the output

## With Bun.serve[​](#with-bunserve "Direct link to With Bun.serve")

When using `Bun.serve` directly (no build step), docxio works out of the box:

```
/** @jsxImportSource docxio */
import { render } from "docxio";

Bun.serve({
  async fetch(req) {
    const doc = (
      <document>
        <section>
          <paragraph><run>Hello from Bun!</run></paragraph>
        </section>
      </document>
    );

    const bytes = await render(doc);
    return new Response(bytes, {
      headers: {
        "Content-Type":
          "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      },
    });
  },
});
```

No build plugin is needed for development -- only for production builds.


---

# @docxio/html

HTML and Markdown export for docxio document trees.

## Installation[​](#installation "Direct link to Installation")

```
npm install @docxio/html
```

**Size:** \~5 KB

## API[​](#api "Direct link to API")

### renderToHtml[​](#rendertohtml "Direct link to renderToHtml")

Converts a docxio document tree to an HTML string.

```
import { renderToHtml } from "@docxio/html";

const html = renderToHtml(doc);
```

Headings map to `<h1>`-`<h6>`, paragraphs to `<p>`, bold runs to `<strong>`, italic to `<em>`, tables to `<table>`, lists to `<ul>`/`<ol>`, hyperlinks to `<a>`, and images to `<img>`.

### renderToMarkdown[​](#rendertomarkdown "Direct link to renderToMarkdown")

Converts a docxio document tree to a Markdown string.

```
import { renderToMarkdown } from "@docxio/html";

const md = renderToMarkdown(doc);
```

Headings map to `#` syntax, bold to `**text**`, italic to `*text*`, tables to pipe tables, lists to `- `or `1. `, hyperlinks to `[text](url)`, and images to `![alt](src)`.

## Example[​](#example "Direct link to Example")

```
/** @jsxImportSource docxio */
import { renderToHtml, renderToMarkdown } from "@docxio/html";

const doc = (
  <document>
    <section>
      <heading level={1}><run>Report</run></heading>
      <paragraph>
        <run>Total: </run>
        <run bold>$1.2M</run>
      </paragraph>
    </section>
  </document>
);

console.log(renderToHtml(doc));
// <h1>Report</h1><p>Total: <strong>$1.2M</strong></p>

console.log(renderToMarkdown(doc));
// # Report\n\nTotal: **$1.2M**
```

## Limitations[​](#limitations "Direct link to Limitations")

* Complex formatting (character spacing, emboss, imprint) is not represented in HTML/Markdown
* Floating image positions are not preserved
* Page breaks and section properties are ignored (HTML/Markdown are flow-based)


---

# @docxio/node

Native Node.js bindings for docxio, powered by [napi-rs](https://napi.rs). Runs Rust code directly without WASM, offering maximum performance for server-side document generation.

## Installation[​](#installation "Direct link to Installation")

```
npm install @docxio/node
```

This installs a platform-specific native binary (no WASM overhead).

## Usage[​](#usage "Direct link to Usage")

The API mirrors the main `docxio` package:

```
import { generate } from "@docxio/node";

const documentTree = {
  type: "document",
  props: { title: "Report" },
  children: [
    {
      type: "section",
      props: {},
      children: [
        {
          type: "paragraph",
          props: {},
          children: [
            { type: "run", props: { bold: true }, children: ["Hello from napi-rs!"] },
          ],
        },
      ],
    },
  ],
};

const bytes = generate(documentTree);
```

## When to use @docxio/node[​](#when-to-use-docxionode "Direct link to When to use @docxio/node")

Use `@docxio/node` instead of the main `docxio` package when:

* You are building a Node.js server and want maximum throughput
* You do not need browser compatibility
* You want to avoid WASM initialization latency

For most projects, the main `docxio` package (WASM-based) is sufficient and works across all runtimes.

## Supported platforms[​](#supported-platforms "Direct link to Supported platforms")

napi-rs provides pre-built binaries for:

* macOS (x64, arm64)
* Linux (x64, arm64)
* Windows (x64)

If a pre-built binary is not available for your platform, installation falls back to compiling from source (requires a Rust toolchain).


---

# @docxio/wasm-minimal

Minimal WASM binary for docxio. Generates OOXML XML parts without ZIP packaging.

## Purpose[​](#purpose "Direct link to Purpose")

The minimal WASM module is optimized for browser environments where bundle size matters. At 441 KB, it is roughly half the size of the full WASM module (920 KB).

The trade-off: it only generates XML parts. ZIP assembly is handled in JavaScript by [`@docxio/zip`](/docs/packages/zip.md).

## What is included[​](#what-is-included "Direct link to What is included")

* Document tree deserialization (serde-wasm-bindgen)
* OOXML XML generation (quick-xml)
* Input validation and sanitization

## What is excluded[​](#what-is-excluded "Direct link to What is excluded")

* ZIP packaging (done by `@docxio/zip` in JS)
* Template parsing and patching
* OOXML validation
* Document tree parsing from JSON

## Usage[​](#usage "Direct link to Usage")

Most users interact with this indirectly through the main `docxio` package:

```
import { render } from "docxio";

const bytes = await render(doc, { backend: "minimal" });
```

## Direct usage[​](#direct-usage "Direct link to Direct usage")

For advanced use cases, you can import the WASM module directly:

```
import init, { generate_document_parts } from "@docxio/wasm-minimal";

await init();

const parts = generate_document_parts(documentTree);
// parts is a Map<string, Uint8Array> of XML file paths to content
```

## Size comparison[​](#size-comparison "Direct link to Size comparison")

| Module                    | Size   | Includes                         |
| ------------------------- | ------ | -------------------------------- |
| `@docxio/wasm-minimal`    | 441 KB | XML generation only              |
| Full WASM (`docxio-wasm`) | 920 KB | XML + ZIP + template + validator |

## Building from source[​](#building-from-source "Direct link to Building from source")

```
wasm-pack build crates/docxio-wasm-minimal --target web --release
```

The output is placed in `crates/docxio-wasm-minimal/pkg/`.


---

# @docxio/zip

JavaScript-side ZIP assembly used by the `"minimal"` WASM backend. This package is an internal dependency -- most users do not need to install it directly.

## Purpose[​](#purpose "Direct link to Purpose")

The minimal WASM binary (441 KB) only generates XML parts. It does not include ZIP packaging to keep the binary small. `@docxio/zip` assembles those XML parts into a valid `.docx` ZIP archive in JavaScript.

## How it works[​](#how-it-works "Direct link to How it works")

```
WASM (minimal)          @docxio/zip
─────────────           ──────────────
generate XML parts  →   assemble ZIP  →  Uint8Array (.docx)
  - document.xml          - [Content_Types].xml
  - styles.xml            - _rels/.rels
  - numbering.xml         - word/document.xml
  - settings.xml          - word/styles.xml
  - header/footer XML     - word/media/*
  - .rels files           - docProps/core.xml
```

## Installation[​](#installation "Direct link to Installation")

This package is automatically installed as a dependency of `docxio` when using the `"minimal"` backend. You do not need to install it separately.

```
# Only if you need it directly
npm install @docxio/zip
```

**Size:** \~8 KB

## API[​](#api "Direct link to API")

```
import { assembleDocx } from "@docxio/zip";

const parts: Record<string, Uint8Array> = {
  "word/document.xml": documentXmlBytes,
  "word/styles.xml": stylesXmlBytes,
  // ...
};

const docxBytes: Uint8Array = assembleDocx(parts);
```

## When is this used?[​](#when-is-this-used "Direct link to When is this used?")

* **Minimal backend** (`backend: "minimal"`): Used automatically
* **Full backend** (`backend: "full"`): Not used -- ZIP is assembled in Rust
* **Auto backend** (default): Used when the minimal backend is selected


---

# Glossary

Key terms and concepts used throughout the docxio documentation.

| Term                  | Definition                                                                                                                                                                                |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Backend**           | The WASM build used for rendering. `"minimal"` (\~600KB, browser-optimized, XML generation only) or `"full"` (\~1.2MB, includes ZIP compression, parser, template engine, and validator). |
| **DocumentNode**      | The JSX tree node type produced by evaluating docxio JSX. Has `type`, `props`, and `children` fields. Passed to `render()` to generate a `.docx` file.                                    |
| **DocumentTree**      | Alias for `DocumentNode` with `type="document"`. The root of the JSX tree.                                                                                                                |
| **EMU**               | English Metric Unit. The base unit for image dimensions in OOXML. 914,400 EMU = 1 inch. Use `widthPt`/`heightPt` props for point-based convenience.                                       |
| **Half-point**        | Unit for font sizes in OOXML. 1 half-point = 0.5pt, so `fontSize={24}` means 12pt.                                                                                                        |
| **Intrinsic element** | A lowercase JSX tag name (e.g., `<paragraph>`, `<run>`) that maps directly to an OOXML construct, as opposed to a user-defined component function.                                        |
| **OOXML**             | Office Open XML (ISO/IEC 29500). The XML-based file format behind `.docx`, `.xlsx`, and `.pptx` files. A `.docx` is a ZIP archive containing XML parts.                                   |
| **Paragraph**         | OOXML's block-level text unit (`w:p`). Contains runs and other inline elements. In docxio: `<paragraph>`.                                                                                 |
| **ParsedTemplate**    | Object returned by `loadTemplate()`. Contains the raw `.docx` bytes and a list of detected `{{slot}}` names.                                                                              |
| **Run**               | OOXML's inline text unit (`w:r`). A contiguous span of text sharing the same character formatting. In docxio: `<run>`.                                                                    |
| **Section**           | A page layout unit (`w:sectPr`) that defines margins, orientation, page size, columns, and headers/footers. Each `<section>` can have different layout settings.                          |
| **Slot**              | A placeholder in a template document. Text slots use `{{name}}` syntax in the `.docx` content. Structured slots use the `<Slot name="...">` JSX component inside `<Template>`.            |
| **SlotValue**         | The type of a template slot value: either a `string` (simple text replacement) or a `DocumentNode` (structured JSX content).                                                              |
| **Theme**             | A TypeScript object implementing the `Theme` interface that provides consistent colors, fonts, and spacing across all document elements.                                                  |
| **Transformer**       | The internal module (`transformer.ts`) that converts the JSX `DocumentNode` tree into a Rust-compatible structure for the WASM boundary.                                                  |
| **Twip**              | "Twentieth of a point" -- the base unit for dimensions in OOXML. 1 twip = 1/20 point = 1/1440 inch. Example: `720` twips = 0.5 inch.                                                      |
| **Validation**        | docxio validates the document tree before rendering. Warnings are logged; in `strict` mode, errors throw.                                                                                 |
| **WASM**              | WebAssembly. The Rust crates compile to WASM, which runs in browsers and server runtimes. docxio auto-initializes the WASM module on first render.                                        |


---