WordTemplater 2.1.7
dotnet add package WordTemplater --version 2.1.7
NuGet\Install-Package WordTemplater -Version 2.1.7
<PackageReference Include="WordTemplater" Version="2.1.7" />
<PackageVersion Include="WordTemplater" Version="2.1.7" />
<PackageReference Include="WordTemplater" />
paket add WordTemplater --version 2.1.7
#r "nuget: WordTemplater, 2.1.7"
#:package WordTemplater@2.1.7
#addin nuget:?package=WordTemplater&version=2.1.7
#tool nuget:?package=WordTemplater&version=2.1.7
WordTemplater
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.
Key Features
- 🎨 Visual Template Design: Design invoices, contracts, and certificates directly in Microsoft Word or LibreOffice.
- ⚡ Zero Office Dependency: 100% managed code built on 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 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).
Multi-Language Ecosystem
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 |
Installation
dotnet add package WordTemplater --version 2.1.6
PackageReference
<PackageReference Include="WordTemplater" Version="2.1.6" />
Quick Start
using System.IO;
using WordTemplater;
var data = new
{
InvoiceNumber = "INV-2026-001",
CreatedAt = DateTime.UtcNow,
Customer = new
{
Name = "Acme Corporation",
Address = new { City = "San Francisco" }
},
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"
};
using (var templateStream = File.OpenRead("Templates/InvoiceTemplate.docx"))
using (var wordTemplate = new WordTemplate(templateStream))
{
wordTemplate.SetWatermark("PAID", color: "22C55E");
wordTemplate.EnableTableZebraStriping(oddColor: "F8FAFC", evenColor: "FFFFFF");
using (var exportedStream = wordTemplate.Export(data))
using (var outputStream = File.Create("Output/Invoice.docx"))
{
exportedStream.CopyTo(outputStream);
}
}
Template Syntax & Evaluators Cheat Sheet
1. Text & String Formatting
| 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______ |
2. Numbers & Currency
| 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% |
3. Dates & Times
| 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 |
4. Logic & Fallbacks
| 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 |
5. Deep JSON & Property Navigation
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.
6. Repeating Lists & Loops
«loop(Employees)»
• Employee: «Name» — Role: «Role» (Row #«_index»)
«endloop»
Loop Metadata Variables
«_index»: 1-based index of the current item (1, 2, 3...)«_first»:trueif current item is the first element«_last»:trueif current item is the last element«_even»:trueif_indexis even (2, 4, 6...)«_odd»:trueif_indexis odd (1, 3, 5...)
7. Repeating Tables & Zebra Striping
| No. | Description | Qty | Unit Price |
|---|---|---|---|
«table(Items)»«_index» |
«Description» |
«Qty» |
«currency(Price)»«endtable» |
Enable alternating shading in template:
«table(Items, 'F8FAFC', 'FFFFFF')»
Or via C# API:
wordTemplate.EnableTableZebraStriping("F8FAFC", "FFFFFF");
8. Images, Barcodes & Media
| Syntax | Supported Data Formats | Description |
|---|---|---|
«image(Avatar)» |
Local file path, HTTPS URL, byte[], Stream, or Base64 string |
Inserts image directly preserving aspect ratio |
«qrcode(Url)» |
String / URL | Automatically renders a 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 | Converts HTML into native OpenXML Word paragraphs |
«word(DocxData)» |
Base64-encoded .docx file |
Merges an entire sub-document into current position |
9. Custom Evaluators
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 evaluator
wordTemplate.RegisterEvaluator("slugify", new SlugifyEvaluator());
Project Repository & Documentation
For full source code, examples, and issues, visit: https://github.com/luuducly/WordTemplater
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- BarcodeLib (>= 3.0.3)
- DocumentFormat.OpenXml (>= 2.20.0)
- Newtonsoft.Json (>= 13.0.3)
- SkiaSharp.NativeAssets.Linux.NoDependencies (>= 2.88.6)
- SkiaSharp.QrCode (>= 0.6.0)
-
net8.0
- BarcodeLib (>= 3.0.3)
- DocumentFormat.OpenXml (>= 2.20.0)
- Newtonsoft.Json (>= 13.0.3)
- SkiaSharp.NativeAssets.Linux.NoDependencies (>= 2.88.6)
- SkiaSharp.QrCode (>= 0.6.0)
-
net9.0
- BarcodeLib (>= 3.0.3)
- DocumentFormat.OpenXml (>= 2.20.0)
- Newtonsoft.Json (>= 13.0.3)
- SkiaSharp.NativeAssets.Linux.NoDependencies (>= 2.88.6)
- SkiaSharp.QrCode (>= 0.6.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
See release notes at https://github.com/luuducly/WordTemplater/releases