Skip to main content

Quick Reference

Single-page cheat sheet for the docxio API.

Components (23)​

Document Structure​

ComponentKey Props
<document>creator, title, description, keywords, styles, useDefaultStyles, theme
<section>pageSize, margins, orientation, columns, columnSpace, lineNumbers, isLastSection

Text​

ComponentKey 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​

ComponentKey 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​

ComponentKey Props
<image>src (required), width, height, widthPt, heightPt, altText, floating, wrapText, floatPosition, format
ComponentKey Props
<hyperlink>url, anchor, tooltip
<bookmark>name (required), id

Headers and Footers​

ComponentKey Props
<header>type: "default" | "first" | "even"
<footer>type: "default" | "first" | "even"

Lists​

ComponentKey Props
<numbered-list>format, start, reference
<bullet-list>reference
<list-item>level (0-8), numbering

Annotations​

ComponentKey Props
<comment>author, date, id
<footnote>id

Breaks and Whitespace​

ComponentKey Props
<pagebreak>--
<linebreak>--
<columnbreak>--
<tab>--
<tabstop>position, type, leader

Fields​

ComponentKey Props
<field>code (required: "PAGE", "NUMPAGES", "DATE", etc.), format

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​

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

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​

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

TypeScript Config​

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

Common Patterns​

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 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​

<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​

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);