WordTemplater is a high-performance, cross-platform .NET library that turns Microsoft Word (.docx) documents into dynamic report templates. Design your templates visually in Microsoft Word using standard MergeFields (or «field» tags), and populate them with complex JSON or C# objects in milliseconds.
No Microsoft Office installation or COM Interop required. Runs seamlessly on Windows, Linux, macOS, Docker containers, and cloud serverless environments.
- Multi-Language Ecosystem
- Key Features
- Installation
- How It Works
- Interactive Desktop GUI Studio
- Quick Start
- Template Syntax & Evaluators Cheat Sheet
- Custom Evaluators (Extensibility)
- Advanced Export Options
- Running Tests & Example Project
- License
WordTemplater is available across multiple programming languages with matching template syntax and feature parity:
| Language | Repository | Package / Install |
|---|---|---|
| C# (.NET) (This repository) | WordTemplater | dotnet add package WordTemplater |
| TypeScript / JavaScript | WordTemplater-ts | npm install wordtemplater-ts |
| Python | WordTemplater-python | pip install wordtemplater |
| Java | WordTemplater-java | com.github.luuducly:wordtemplater |
- 🎨 Visual Template Design: Design invoices, contracts, and certificates directly in Microsoft Word or LibreOffice.
- ⚡ Zero Office Dependency: 100% managed code built on DocumentFormat.OpenXml.
- 🐧 True Cross-Platform: Fully tested on Linux, macOS, and Windows. Multi-targeted for .NET 8 (LTS), .NET 9, and .NET 10.
- 🧭 Deep JSON Navigation: Access nested fields (
Customer.Address.City) and array indices (Items[0].Name) case-insensitively. - 📊 Table & Loop Automation: Effortless table row cloning, dynamic alternating zebra-striping, and loop metadata (
_index,_first,_last,_even,_odd). - 🖼️ Multi-Format Media Insertion:
- Images directly from file paths, HTTPS URLs,
byte[],Stream, or Base64 strings. - Dynamic QR Codes and Code128 Barcodes.
- Flowcharts and state diagrams via Mermaid.
- Raw HTML and nested sub-DOCX documents.
- Images directly from file paths, HTTPS URLs,
- 🛡️ Document Watermarking: Inject customizable diagonal or horizontal text watermarks into all sections/headers dynamically.
- 🧩 Extensible Plugin Engine: Register custom evaluators and formatters with a single interface (
IEvaluator).
Install the package via NuGet:
dotnet add package WordTemplater --version 2.1.6Install-Package WordTemplater -Version 2.1.6<PackageReference Include="WordTemplater" Version="2.1.6" />WordTemplater bridges visual document authoring in Microsoft Word with high-performance, automated data binding:
-
Design Visually in Microsoft Word:
- Insert standard Word MergeFields (
Ctrl + F9orInsert -> Quick Parts -> Field -> MergeField) or simple guillemets («field»). - Use built-in formatters and evaluators directly within field codes:
- Text & Padding:
«upper(Name)»,«padleft(DocId, 8, '0')»,«date(CreatedAt, 'dd/MM/yyyy')» - Financial & Numeric:
«currency(Total, 'vi-VN')»,«percentage(TaxRate)»,«number(Qty, '#,##0')» - Machine-Readable Identifiers:
«qrcode(Url)»,«barcode(Sku)»,«image(Logo)» - Rich Media & Ingestion:
«html(Notes)»,«mermaid(WorkflowDiagram)» - Conditional Branches:
«if(Score >= 80, 'VIP Tier', 'Standard')» - Dynamic Tables & Loops:
«table(Products)»...«endtable»,«loop(Items)»...«endloop» - Exact Pre-printed Overlays: Absolute-positioned DrawingML Text Shapes positioned seamlessly over pre-printed dot lines (
.......) in headers, bodies, or footers.
- Text & Padding:
- Insert standard Word MergeFields (
-
Supply Data:
- Bind any data model: C# POCO classes, anonymous objects,
Newtonsoft.Json.Linq.JObject, raw JSON strings, or dictionaries. - Access deeply nested properties (
Customer.Address.City) and array items (Items[0].Price) case-insensitively.
- Bind any data model: C# POCO classes, anonymous objects,
-
Export High-Fidelity Documents:
- WordTemplater parses the document XML, clones repeating table rows, formats numbers/dates, renders QR/barcodes/diagrams, and outputs a complete
.docxfile or memory stream in milliseconds with zero Microsoft Office dependency.
- WordTemplater parses the document XML, clones repeating table rows, formats numbers/dates, renders QR/barcodes/diagrams, and outputs a complete
A cross-platform desktop application built with Avalonia UI is included directly in the repository at examples/WordTemplater.Desktop. It allows developers and designers to test features, experiment with templates, edit JSON payloads, and inspect generated documents instantly on macOS, Linux, and Windows.
Run the application with a single CLI command from the repository root:
dotnet run --project examples/WordTemplater.Desktop- 🌟 Built-in Interactive Templates:
- Enterprise Full Showcase: Comprehensive template demonstrating QR codes, Code128 barcodes, raster images, inline conditions, HTML altChunks, Mermaid diagrams, table row cloning, and currency formatters.
- Pre-printed Bill / Voucher: Demonstrates absolute DrawingML Text Shapes positioned directly over pre-printed dotted blank lines (
.....) across Header, Body, and Signatures. - Invoice & Employee Summaries: Tables with dynamic zebra striping, currency formatters, and deep JSON structures.
- Custom DOCX Picker: Load and test your own external
.docxtemplate files.
- ✏️ Direct In-Word Template Redesign:
- Click the "✏️ Mở File Template trong Word (.docx)" button to immediately open any template in Microsoft Word.
- Drag, resize, or reposition text shapes and edit fields visually in Word, save (
Cmd + S/Ctrl + S), and the Desktop App automatically reloads your changes on the next export.
- 📝 Live JSON Editor:
- Full-featured JSON editor with automatic sample data population for each template.
- ✨ Format JSON button for instant pretty-printing and formatting.
- 🎨 Visual Export Controls:
- Toggle and customize dynamic text watermarks (text, hex color, rotation angle).
- Enable table zebra striping with custom odd and even row background colors.
- ⚡ Instant Export & Document Viewer:
- Click "⚡ Generate & Export Document" to render in milliseconds.
- Click "📖 Open Exported Document (.docx)" to inspect the finished document in your default word processor.
using System.IO;
using Newtonsoft.Json.Linq;
using WordTemplater;
// 1. Prepare your data model (POCO or JSON)
var data = new
{
InvoiceNumber = "INV-2026-001",
CreatedAt = DateTime.UtcNow,
Customer = new
{
Name = "Acme Corporation",
Address = new { City = "San Francisco", Country = "USA" }
},
Items = new[]
{
new { Description = "Cloud Hosting", Qty = 1, Price = 1200.00 },
new { Description = "Domain Registration", Qty = 2, Price = 15.00 }
},
CompanyLogo = "https://example.com/logo.png", // URL, file path, byte[], or base64
QrData = "https://invoice.example.com/pay/INV-2026-001"
};
// 2. Load template and export
var templatePath = "Templates/InvoiceTemplate.docx";
var outputPath = "Output/Invoice.docx";
using (var templateStream = File.OpenRead(templatePath))
using (var wordTemplate = new WordTemplate(templateStream))
{
// Optional: Add watermark and zebra-striping
wordTemplate.SetWatermark("PAID", color: "22C55E", angle: -45, fontSize: 80);
wordTemplate.EnableTableZebraStriping(oddColor: "F8FAFC", evenColor: "FFFFFF");
using (var exportedStream = wordTemplate.Export(data))
using (var outputStream = File.Create(outputPath))
{
exportedStream.CopyTo(outputStream);
}
}
Console.WriteLine($"Generated: {outputPath}");| Placeholder Syntax | Description | Example Input | Example Output |
|---|---|---|---|
«upper(Name)» |
Converts text to uppercase | "acme corp" |
ACME CORP |
«lower(Code)» |
Converts text to lowercase | "PROD-XYZ" |
prod-xyz |
«trim(Note)» |
Trims leading/trailing whitespace | " hello " |
hello |
«sub(Text, 0, 4)» |
Substring (start, length) |
"WORDTEMPLATER" |
WORD |
«left(Code, 3)» |
First N characters |
"INV-9988" |
INV |
«right(Code, 4)» |
Last N characters |
"INV-9988" |
9988 |
«replace(Text, '-', '/')» |
Replaces occurrences of string | "2026-10-15" |
2026/10/15 |
«padleft(Number, 6, '0')» |
Left-pads string to target length | 42 |
000042 |
«padright(Code, 8, '_')» |
Right-pads string to target length | "A1" |
A1______ |
| Placeholder Syntax | Description | Example Input | Example Output |
|---|---|---|---|
«currency(Amount)» |
Formats as currency using current/specified culture | 1500000 |
$1,500,000.00 |
«currency(Amount, 'vi-VN')» |
Currency with explicit culture | 1500000 |
1.500.000 ₫ |
«number(Score, '#,##0.00')» |
Formats number with custom format pattern | 12345.6 |
12,345.60 |
«number(Score, '#,##0', 'de-DE')» |
Number format with target culture | 1234567 |
1.234.567 |
«percentage(Ratio)» |
Formats number as percentage | 0.85 |
85.00% |
| Placeholder Syntax | Description | Example Input | Example Output |
|---|---|---|---|
«date(CreatedAt, 'dd/MM/yyyy')» |
Formats date with pattern | 2026-10-15T09:00:00 |
15/10/2026 |
«date(CreatedAt, 'yyyy-MM-dd HH:mm')» |
Formats date and time | DateTime object | 2026-10-15 09:00 |
«date(CreatedAt, 'MMMM yyyy', 'vi-VN')» |
Formats date with localized culture | 2026-10-15 |
tháng mười 2026 |
| Placeholder Syntax | Description | Example Input | Example Output |
|---|---|---|---|
«default(Phone, 'N/A')» |
Returns fallback value if null, empty, or missing | null |
N/A |
«coalesce(TaxCode, 'Unregistered')» |
Synonym for default |
"" |
Unregistered |
«if(IsVIP, 'Gold Member', 'Standard')» |
Outputs different strings depending on boolean | true |
Gold Member |
WordTemplater seamlessly resolves nested properties and array indices:
«Customer.Company.LegalName»
«Customer.BillingAddress.City»
«Orders[0].TrackingCode»
«Department.Managers[0].Contact.Email»
Property name matching is case-insensitive, matching both C# PascalCase conventions and JSON camelCase.
Repeat an arbitrary paragraph, block, or bullet point:
«loop(Employees)»
• Employee: «Name» — Role: «Role» (Row #«_index»)
«endloop»
Within any «loop(...)» or «table(...)» block, the following metadata fields are automatically available:
| Variable | Type | Description |
|---|---|---|
«_index» |
int |
1-based index of the current item (1, 2, 3...) |
«_first» |
bool |
true if current item is the first element |
«_last» |
bool |
true if current item is the last element |
«_even» |
bool |
true if _index is even (2, 4, 6...) |
«_odd» |
bool |
true if _index is odd (1, 3, 5...) |
Repeat rows in a Word table:
| No. | Description | Qty | Unit Price |
|---|---|---|---|
«table(Items)»«_index» |
«Description» |
«Qty» |
«currency(Price)»«endtable» |
You can enable table zebra striping in two ways:
- Inside the Word Template:
«table(Items, 'F8FAFC', 'FFFFFF')» - In C# Code:
wordTemplate.EnableTableZebraStriping(oddColor: "F8FAFC", evenColor: "FFFFFF");
| Syntax | Supported Data Formats | Description |
|---|---|---|
«image(Avatar)» |
Local file path (/path/to/img.png), HTTPS URL (https://...), byte[], Stream, or Base64 string |
Inserts image directly into the placeholder run preserving aspect ratio |
«qrcode(Url)» |
String / URL | Automatically renders a vector-crisp QR code image |
«barcode(Sku)» |
String / Numeric code | Generates a 1D Code128 barcode |
«mermaid(Diagram)» |
Mermaid graph syntax text | Automatically renders Mermaid text into a diagram image |
«html(Content)» |
HTML string (e.g. <b>Bold</b> text) |
Converts HTML into native OpenXML Word paragraphs |
«word(DocxData)» |
Base64-encoded .docx file |
Merges an entire sub-document into the current position |
Template field: «mermaid(WorkflowDiagram)»
Data:
data["WorkflowDiagram"] = @"
graph LR
A[Order Placed] --> B(Payment Authorized)
B --> C[Fulfillment]
C --> D((Delivered))
";Add diagonal or horizontal text watermarks across the exported document:
// Fluent API on WordTemplate:
wordTemplate.SetWatermark(
text: "CONFIDENTIAL",
color: "E2E8F0", // Hex color (without # or with #)
angle: -45, // Rotation angle in degrees
fontSize: 72, // Font size in points
fontName: "Calibri" // Font family name
);Extend WordTemplater with your own custom logic by implementing IEvaluator:
using WordTemplater;
public class SlugifyEvaluator : IEvaluator
{
public string? Evaluate(object? value, List<object> parameters)
{
if (value == null) return null;
var text = value.ToString() ?? "";
return text.ToLowerInvariant().Replace(" ", "-");
}
}
// Register with WordTemplate:
using var wordTemplate = new WordTemplate(templateStream);
wordTemplate.RegisterEvaluator("slugify", new SlugifyEvaluator());Now you can use it directly in your Word template:
«slugify(ProductTitle)»
Control export behavior using ExportOptions:
var options = new ExportOptions
{
RemoveFallback = true, // Cleans up legacy VML fallback nodes
WatermarkText = "DRAFT - REVIEW ONLY", // Injected watermark text
WatermarkColor = "EF4444", // Hex color
WatermarkAngle = -30, // Angle
TableOddRowColor = "F9FAFB", // Alternating table row background
TableEvenRowColor = "FFFFFF"
};
using var resultStream = wordTemplate.Export(data, options);dotnet test src/WordTemplater.slndotnet run --project src/WordTemplater.Example/WordTemplater.Example.csprojThe sample project reads sample JSON data from DataSamples/Data.json, processes Templates/Template.docx, and outputs Output.docx.
dotnet run --project examples/WordTemplater.Desktop/WordTemplater.Desktop.csprojInteractive desktop GUI tool powered by Avalonia UI for testing custom JSON payloads, picking built-in or custom Word templates, configuring watermarks and zebra-striping, and immediately opening the exported .docx document.
This project is licensed under the MIT License. Feel free to use it in personal, open-source, or commercial projects.
