---
title: "Reuse Word sub-templates | Nutrient Java SDK"
canonical_url: "https://www.nutrient.io/guides/java/templates/word-sub-templates/"
md_url: "https://www.nutrient.io/guides/java/templates/word-sub-templates.md"
last_updated: "2026-11-20T00:00:00.000Z"
description: "Reuse letterheads, terms, and signature blocks as Word sub-templates and generate a PDF using Nutrient Java SDK."
---

# Reuse Word sub-templates

Business documents reuse the same building blocks. Letters, quotes, and contracts share a letterhead, standard terms, and a signature block. When each template holds its own copy of these blocks, a new office address means editing every template.

Sub-templates keep each building block in a Word file of its own. The main template holds a placeholder where the block goes, and the JSON model names the file for that placeholder. Nutrient Java SDK inserts the file’s content when it generates the document. A sub-template is a template too, so the same JSON data fills its placeholders.

This guide generates a letter whose page header, terms, and signature come from three sub-templates. It builds on the [Word template generation](https://www.nutrient.io/guides/java/templates/word-template-generation.md) guide.

[Download sample](https://www.nutrient.io/downloads/samples/java/word-sub-templates.zip)

## How sub-templates work

Nutrient replaces a placeholder with a sub-template when the placeholder’s value in the JSON model is an object with `"_type": "docx"`. The object names the Word file with one of the following properties:

- `path`: The path to the DOCX file. A relative path starts from the application’s working directory.

- `data`: The content of the DOCX file in base64, plain or as a `data:` URI.

```json

"model": {
    "letterhead": { "_type": "docx", "path": "input_letterhead.docx" },
    "terms": { "_type": "docx", "data": "UEsDBBQABgAIAAAAIQ..." },
    "companyName": "Nutrient"
}

```

The content of the sub-template replaces the placeholder as follows:

- The paragraphs, tables, and pictures of the sub-template replace a placeholder that’s alone in its paragraph.

- A placeholder inside text splits the paragraph. The text before and after the placeholder stays in paragraphs of its own.

- Placeholders work in the body, in table cells, and in page headers and footers.

The inserted content keeps its formatting. Nutrient copies the styles, lists, pictures, links, footnotes, and bookmarks that the sub-template uses. When the main template already has a style with the same ID, the style of the main template applies, as when Word inserts a file. The headers, footers, page setup, and comments of the sub-template aren’t copied.

## Prepare the templates

The sample uses four Word files and one JSON model:

- `input_letter_template.docx`: The letter. Its page header holds `{{letterhead}}`. Its body holds the address of the customer, a table with one row per ordered item, `{{terms}}`, and `{{signature}}`.

- `input_letterhead.docx`: The company logo next to `{{companyName}}`, `{{companyStreet}}`, `{{companyCity}}`, and `{{companyPhone}}`.

- `input_letter_terms.docx`: A heading and a numbered list that uses `{{deliveryDays}}` and `{{paymentDays}}`, with a footnote.

- `input_letter_signature.docx`: `{{senderName}}` in bold and `{{senderRole}}` in a style of its own.

- `input_letter_model.json`: The data. It names the three sub-templates and holds the values of every placeholder.

The model holds the sub-templates next to the plain values:

```json

{
    "config": {
        "delimiter": {
            "start": "{{",
            "end": "}}"
        }
    },
    "model": {
        "letterhead": { "_type": "docx", "path": "input_letterhead.docx" },
        "terms": { "_type": "docx", "path": "input_letter_terms.docx" },
        "signature": { "_type": "docx", "path": "input_letter_signature.docx" },
        "companyName": "Nutrient",
        "companyStreet": "100 Main Street",
        "companyCity": "San Francisco, CA 94105",
        "companyPhone": "+1 415 555 0100",
        "date": "29 October 2026",
        "customerName": "Jane Smith",
        "customerStreet": "42 Oak Avenue",
        "customerCity": "Austin, TX 78701",
        "orderNumber": "SO-1042",
        "items": [
            { "name": "Document SDK license", "qty": "1", "price": "$4,800" },
            { "name": "Support plan", "qty": "1", "price": "$1,200" }
        ],
        "deliveryDays": "5",
        "paymentDays": "30",
        "senderName": "Alex Taylor",
        "senderRole": "Account Manager"
    }
}

```

`{{companyName}}` appears in the letterhead and in the footer of the letter. One value fills both.

## Complete implementation

The code is the same as for any Word template. The model names the sub-templates, so the code needs no extra call. Start with the package declaration and the imports:

```java

package io.nutrient.Sample;

import io.nutrient.sdk.Document;
import io.nutrient.sdk.exceptions.NutrientException;
import io.nutrient.sdk.editors.WordEditor;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;

public class WordSubTemplates {
    public static void main(String[] args) {

```

Open the letter template. The [try-with-resources](https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html) syntax closes the document automatically:

```java

        try (Document document = Document.open("input_letter_template.docx")) {

```

Create a `WordEditor` instance for template processing:

```java

            WordEditor editor = WordEditor.edit(document);

```

Read the JSON model and stop if the file can’t be read:

```java

            String model = null;
            try {
                model = Files.readString(Path.of("input_letter_model.json"));
            } catch (IOException e) {
                System.err.println("Failed to read template model file");
                System.exit(1);
            }

```

Apply the model. This call fills the placeholders of the letter, then opens each sub-template that a placeholder refers to, fills it from the same data, and inserts its content in place of its placeholder:

```java

            editor.applyTemplateModel(model);

```

Save the generated letter to a new file. The `catch` block reports any `NutrientException`, including one for a sub-template that can’t be used:

```java

            editor.saveWithModelAs("output.docx");
            System.out.println("Successfully generated the letter from its sub-templates");
        } catch (NutrientException e) {
            System.err.println("Error: " + e.getMessage());
            System.exit(1);
        }
    }
}

```

The page header of `output.docx` shows the letterhead with its logo and the company address. The body shows the terms with their numbered list and footnote, followed by the signature.

## Use sub-templates in loops

Inside a loop, a sub-template reads the values of the current record first, then the values around the loop. Each record can also name a sub-template of its own. For example, a template paragraph that holds `{{#sections}}{{content}}{{/sections}}` receives one document per record from the following model. `warranty.docx` fills `{{years}}`, and `returns.docx` fills `{{days}}`, from their own records:

```json

"model": {
    "sections": [
        { "content": { "_type": "docx", "path": "warranty.docx" }, "years": "2" },
        { "content": { "_type": "docx", "path": "returns.docx" }, "days": "30" }
    ]
}

```

Each copy of a sub-template gets lists of its own, so a numbered list starts at 1 in every copy.

## Error handling

`applyTemplateModel` throws a `NutrientException` when a sub-template can’t be used. This happens in the following cases:

- The file or its folder doesn’t exist.

- The file can’t be read, for example because of its permissions.

- The file isn’t a Word document.

- The value has neither `path` nor `data`, or `data` is empty or isn’t valid base64.

- A sub-template includes itself, directly or through other sub-templates. Nutrient stops after 10 levels of nesting.

The whole document fails in these cases, so Nutrient never generates a letter without its letterhead.

## Limitations

- Sub-templates work in Word templates only. PowerPoint and Excel templates reject a `docx` value.

- Nutrient inserts only the body of a sub-template. Placeholders in its footnotes and endnotes aren’t filled.

- Page headers and footers can’t hold footnotes or endnotes. In a header or footer, Nutrient removes the note references of a sub-template.

- Image caption numbers restart in each sub-template.

- A placeholder inside an inline content control receives only the text of the sub-template, one line per paragraph.

- `path` reads any file that the application can access. Don’t build the path from untrusted input.

## Conclusion

Sub-templates use the same three steps as any Word template: open the template, apply the model, and save the result. The model names each sub-template, and Nutrient fills it from the same data before inserting it. To convert the letter to an accessible PDF, refer to the [Word template to PDF/UA](https://www.nutrient.io/guides/java/templates/word-template-to-pdf-ua.md) guide.

Download the [sample package](https://www.nutrient.io/downloads/samples/java/word-sub-templates.zip) to run this example as-is.
---

## Related pages

- [Nutrient Java SDK template guides](/guides/java/templates.md)
- [Generating PDF/UA from PowerPoint templates](/guides/java/templates/presentation-template-to-pdf-ua.md)
- [Generating PDF/UA from Excel templates](/guides/java/templates/spreadsheet-template-to-pdf-ua.md)
- [Word template generation and processing](/guides/java/templates/word-template-generation.md)
- [Word template processing-to-PDF/UA conversion](/guides/java/templates/word-template-to-pdf-ua.md)

