Template API

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

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

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

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

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

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

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