Function populateDocumentTemplate

Promise that resolves to an ArrayBuffer containing the populated DOCX file

Pipeline overview

1. Prepare a DOCX file containing placeholder tags (e.g. {{name}})
2. Call populateDocumentTemplate() with your configuration and template data
3. Load the returned ArrayBuffer directly with load(), or pass it to convertToPDF() first

Template syntax

Placeholders let users substitute a marker with some text, loops generate repetitions of a given pattern, and image markers insert images into the output DOCX.

Delimiters

Delimiters wrap every placeholder in the DOCX template. When config is omitted, delimiters default to single braces: { and }. To use custom delimiters such as {{ and }}, pass them explicitly in config:

config: {
  delimiter: {
    start: '{{',
    end: '}}',
  },
}
Copy

By default, dotted markers such as {{account.name}} are treated as object path navigation, where . separates each level. To treat dots as literal characters in a key name instead, set objectDelimiter to a different character — that character then becomes the path separator, and dots are treated as literals:

config: {
  delimiter: {
    start: '{{',
    end: '}}',
    objectDelimiter: '|',
  },
}
Copy

With this config, {{account.name}} resolves the literal key "account.name", while {{account|name}} navigates to account.name in the model.

Simple substitution

{{name}} is replaced with the value of name in the model. Supported value types include strings, numbers, booleans, null, objects, and arrays. For the full type definition see TemplateDataToPopulateDocument.

Conditionals and loops

The # and / tags serve double duty depending on the model value type:

• When the value is a boolean or truthy scalar, the block acts as a conditional:

{{#isActive}}This appears when isActive is true.{{/isActive}}
Copy

• When the value is an array, the block acts as a loop, repeating once per item:

{{#items}}{{name}} — {{price}}{{/items}}
Copy

• The ^ prefix renders the block when the value is falsy (the inverse/else branch):

{{^isActive}}This appears when isActive is false.{{/isActive}}
Copy

Example combining conditionals and inverse sections:

{{#isCool}}You're cool.{{/isCool}}
{{^isCool}}You're not cool.{{/isCool}}
Copy

{
  model: {
    isCool: false
  }
}
Copy

Output: You're not cool.

Loops

For instance if the document contains:

{#ITEMS} {name} {price} {/ITEMS}
Copy

Here, ITEMS is the name of the loop template marker, and name and price are regular placeholder template markers over which the SDK iterates replacing the name placeholder with corresponding name value in model, and similarly the price placeholder is replaced by the corresponding price value in model.

{
  model: {
    items: [
      {
        name: "A",
        price: 10
      },
      {
        name: "B",
        price: 15
      }
    ]
  }
}
Copy

Loops can be nested to any depth:

{
  model: {
    level0: [
      {
        label: "Group A",
        level1: [
          {
            label: "Item 1",
            level2: [
              { label: "Sub-item 1a" },
              { label: "Sub-item 1b" }
            ]
          }
        ]
      }
    ]
  }
}
Copy

Image markers

You can author image markers in DOCX templates using:

• {{%name}} for inline image placement
• {{%%name}} for centered image placement

Supported sources in standalone mode:

• source: "base64" with raw base64 payload (data) or data URL payload
• source: "dataUrl" as an alias for base64 (normalized at runtime)
• source: "url" for HTTP(S) URLs (fetched and normalized to base64 at runtime)

Unsupported in public APIs:

• source: "file" (there is no filesystem semantic for public standalone usage)
• format: "svg" / image/svg+xml payloads

For source: "url", cross-origin requests require proper CORS headers from the image host. If CORS is not configured, pass base64/data URL payloads instead.

When using source: "url", image format is resolved in the following order:

1. Explicit format property
2. MIME type from the HTTP response
3. File extension from the URL

If none of these can be determined, the request will fail.

Supported format values: png, jpg/jpeg, gif, bmp, tif/tiff. The aliases jpeg and tiff are normalized to jpg and tif respectively.

Sizing validation rules:

• sizing: "original" requires no dimensions.
• sizing: "fixed" and sizing: "fit-max" require width and height (> 0).
• sizing: "fit-width" requires width (> 0).
• sizing: "fit-height" requires height (> 0).

Additional image properties:

Example image model value:

{
  _type: "image",
  source: "base64",
  data: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIHWP8z8DwHwAF+wJ/lxS6RQAAAABJRU5ErkJggg==",
  format: "png",
  sizing: "fit-width",
  width: 96,
  caption: "Company logo",
  altText: "Logo"
}
Copy

Multipage image payloads can use pageNumber (1-based index).

The API rejects the whole request when any image payload fails validation or URL resolution.

Cancellation

This operation respects the signal property in the configuration object. Pass an AbortSignal to cancel a long-running template population:

const controller = new AbortController()

const arrayBuffer = await NutrientViewer.populateDocumentTemplate(
  {
    document: '/sales-report.docx',
    licenseKey: 'YOUR_LICENSE_KEY',
    signal: controller.signal,
  },
  { model: { name: 'Alex' } },
)

// To cancel:
controller.abort()
Copy

Error reference

The promise rejects with a NutrientViewer.Error in the following cases:

• Invalid configuration
• Any image payload failing validation or URL resolution
• CORS failure when using source: "url"
• Operation cancelled via AbortSignal