Docxtemplater uses various types of tags to manage template data and control how the document is generated. This guide explains the different tags available, their syntax, and how to use them effectively in your templates.
Tags in Docxtemplater are enclosed in curly braces : { and }. There are several types of tags, each serving a different purpose:
{first_name}; These tags are used to insert data values (text) directly into the template.{#loop} and {/loop}; These tags define a loop for repeating sections based on array data.{#condition} and {/condition}; These tags are used to conditionally include or exclude content based on boolean values.{@input}; These tags are used to insert raw XML data into the document.{%src_url}; Used with the image-module to insert images from URLs.{~~html}; Used with the html-module to insert HTML (tables, formatted text, ordered or unordered lists){:include doc}; Used with the subtemplate-module to insert the full content of an other docx file{$data}; Used with the chart-module to replace the data of a given docx/pptx native chart.The syntax of Docxtemplater tags is inspired by the Mustache templating language.
Placeholder tags are used to insert data into the template. For example, with a tag like {name}, Docxtemplater will replace {name} with the corresponding value from the data object
With this template (input.docx):
And given the following data (data.json):
{
"name": "John"
}
docxtemplater will produce (output.docx):
Condition tags control whether certain parts of the template are rendered based on the provided data.
{#your_condition} starts a condition block{/your_condition} ends it.Our goal here is to create a template that displays a Cat's name or Dog's name if and only if the data file says to do so.
With this template:
and this data:
{
"hasKitty": true,
"kitty": "Minie"
"hasDog": false,
"dog": null
}
docxtemplater will render the following:
For more details on conditions, see Sections
You can also create "else" blocks with Inverted Sections
A loop tag enables docxtemplater iterating over the data, for instance coping with arrays.
Conditions and loops use the same syntax.
{#your_loop} starts a loop{/your_loop} ends it.Our goal is to create a template that will be filled with data in an array of software licenses. For each license, the name and price need to be output.
With this template:
Given the following data:
{
"products": [
{ "name": "Windows", "price": 100 },
{ "name": "Mac OSX", "price": 200 },
{ "name": "Ubuntu", "price": 0 }
]
}
docxtemplater will render :
To loop over an array containing primitive data (eg string):
Given the following template:
and following data:
{
"products": ["Windows", "Mac OSX", "Ubuntu"]
}
Will result in:
Sections allow you to include blocks of content that are conditionally rendered based on the provided data.
{#your_section} starts a section{/your_section} ends it.| Type of the value | the section is shown | scope |
|---|---|---|
| falsy or empty array | never | NA |
| non empty array | for each element of array | element of array |
| object | once | the object |
| other truthy value | once | unchanged |
This table shows for each type of value, whether or not the section content is rendered and what is the scope of that section.
Non empty array
Our goal here is to output a list of fruits.
Given the following template,
and given the following data:
{
"fruits": ["banana", "apple"]
}
docxtemplater will output:
Empty array
Given the following template
Given the following data:
{
"fruits": []
}
docxtemplater will output an empty document:
Object
In this scenario, the people data is a single object representing one person with details like name, age, and occupation.
Given the following template
Given the following data:
{
"people": {
"name": "Alice",
"age": 30,
"occupation": "Engineer"
}
}
docxtemplater will output document:
Explanation: {#people} opens the section where people is the context. Inside the section, {name} refers to people.name, {age} refers to people.age, and {occupation} refers to people.occupation. Since people is an object, docxtemplater accesses its properties directly within the section.
Truthy value
If the value is of type boolean, the section is shown once if the value is true, and the scope of the section is unchanged.
If we have the following template,
and the following data,
{
"hasProduct": true,
"price": 10
}
docxtemplater will output:
Since hasProduct is a boolean, the section is shown once if hasProduct is true. Since the scope is unchanged, the subsection {price} € rendered as [10 €]
This is precisely the behavior of a condition tag. In fact, a condition
tag is a section tag.
To create tables with varying numbers of rows, use loop tags within table cells.
You need to place the start of a loop in the first column cell, and the end of the loop in the last cell of the same row.
Our goal here is to create a table that contains name, age and phone number for each of our users.
If we have the following template:
| Name | Age | Phone Number |
|---|---|---|
| {#users}{name} | {age} | {phone}{/} |
Given the following data:
{
"users": [
{
"name": "John",
"age": 22,
"phone": "+33777777777"
},
{
"name": "Mary",
"age": 25,
"phone": "+33666666666"
}
]
}
Will render the following :
| Name | Age | Phone Number |
|---|---|---|
| John | 22 | +33777777777 |
| Mary | 25 | +33666666666 |
docxtemplater automatically interprets the closing tag {/} as{/users}.
Inverted sections are the opposite of regular sections; they render content if the key doesn't exist, is false, or is an empty list.
{^your_inverted_section} begins a "your_inverted_section" inverted section{/your_inverted_section} ends it.Template:
Data:
{
"repo": []
}
Output:
Explanation:
Because repo is an empty array, the inverted section using repo is rendered but not the section.
If you need to render a complex table or an equation, it's possible to insert raw (unescaped) XML.
-{@input} inserts raw XML data
We want to add to the template a Word Paragraph written in rawXml.
Given the following template:
with this data,
doc.render({
rawXml: `
<w:p>
<w:r>
<w:rPr>
<w:color w:val="FF0000"/>
</w:rPr>
<w:t>
My custom
</w:t>
</w:r>
<w:r>
<w:rPr>
<w:color w:val="00FF00"/>
</w:rPr>
<w:t>
XML paragraph
</w:t>
</w:r>
</w:p>
`,
});
docxtemplater will render:
My custom XML paragraph
With the rawXML syntax the whole current paragraph (<w:p> tag) is
replaced by the XML passed in the value.
For inserting HTML directly into your document, use the docxtemplater html module. Refer to its specific documentation for more details.
In docxtemplater, newlines (paragraph breaks) are handled in a straightforward manner, but the interaction between docxtemplater tags and newlines can sometimes lead to unexpected outputs.
To manage newlines effectively, you can use the paragraphLoop option to remove unwanted line breaks.
If your docxtemplater template includes paragraph breaks within a section, those newlines will also appear in the output by default.
Given the template,
and the data,
{
"repo": [{ "name": "John" }, { "name": "Jane" }]
}
the output with the default settings will be :
(where NL represents an emptyline)
docxtemplater iterates over each item in the repo array. For
each item, it outputs {name} and includes the newlines present in the
template.
Enable the paragraphLoop option to avoid these paragraph breaks:
const doc = new Docxtemplater(zip, { paragraphLoop: true });
// Now, all sections in the form of :
// {#section}
// something
// {/section}
// will keep just the inner paragraphs, and drop the newlines of the outer section
doc.render(/* data */);
Alternatively (less recommended), manually remove the newlines:
For our example , that would be:
This would render:
A Lambda refers to a function that is defined without being bound to an identifier. This is a common feature of JavaScript. You can use lambdas in docxtemplater to perform custom processing.
Given the following Javascript:
const doc = new Docxtemplater(zip);
doc.render({
userGreeting: (scope) =>
"How is it going, " + scope.user + " ?",
users: [
{
name: "John",
},
{
name: "Mary",
},
],
});
with the following template :
Docxtemplater will render :
Docxtemplater will call the function userGreeting twice (one for the user "John", and for the user "Mary").
The {#users} section loops over each user. Inside the section, the scope is set to the current user being processed. As userGreeting is taking the scope as first argument and the scopeManager as a second argument implicitly, userGreeting is fed with the current user.
Technical note: if you're not familiar with the concept of scope, the scope determines which data is available at different points in the template and drives the rendering of placeholders and functions. This is an important notion to know in JavaScript and other programming languages.
docxtemplater templates use default delimiters { and } to enclose placeholders and logic.
Problem: If your template also needs to contain "{" or "}" characters outside of tags, you might need to change the delimiter tag from inside your template.
Solution: By customizing delimiters, you avoid conflicts and ensure that docxtemplater correctly interprets your template placeholders.
In order to customize the delimiters you can use our 'Set Delimiter tags'. A 'Set Delimiter tags' starts with an equal sign and changes the tag delimiters from { and } to custom strings.
Given the following template:
The following data:
{
"first_name": "John",
"last_name": "Doe"
}
Docxtemplater will output:
Technical note: custom delimiters may not contain whitespace or the equals sign.
You can change the delimiters globally by using docxtemplater options object.
If you want to use a tag like {=foo}, you can remove the default "change delimiter" tag behavior by using the following code:
const doc = new Docxtemplater(zip, {
paragraphLoop: true,
linebreaks: true,
syntax: {
changeDelimiterPrefix: null,
},
});
doc.render(data);
To use a different character, such as $, to change delimiters, use the following code:
const doc = new Docxtemplater(zip, {
paragraphLoop: true,
linebreaks: true,
syntax: {
changeDelimiterPrefix: "$",
},
});
doc.render(data);
That way,
Using the following template,
with the following data:
{
"first_name": "John"
}
docxtemplater will render:
In docxtemplater, the Dash syntax provides a way to control how sections are rendered, especially when looping over elements in a DOCX template. It helps specify where and how the loop should expand, making template rendering more flexible.
If between the two tags {#tag}______{/tag}
<w:tc> or <a:tc>) , that means that your loop is inside a table, and it will expand the loop over the table row (<w:tr> or <a:tr>).With Dash syntax, you can explicitly specify the tag to loop over. For instance, if you want to loop over paragraphs (w:p), creating a new paragraph for each item, you can write:
Given the following data,
{
"users": [{ "name": "John" }, { "name": "Mary" }]
}
using the following template,
docxtemplater will render:
The example above has created two paragraphs (one for each user). If you
were using a normal loop like {#users}{name}{/}, it would output each user
name on the same paragraph.