Function populateDocumentTemplate

Promise that resolves to an ArrayBuffer containing the populated DOCX, XLSX, or PPTX file

Pipeline overview

1. Prepare a DOCX, XLSX, or PPTX 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

Supported formats

DOCX templates support placeholders, loops, conditions, and images in document content.

XLSX templates process every worksheet and support placeholders, conditions, row loops, images, and typed number, date, percentage, and boolean cells. Column loops and list expansion within a single cell aren't supported. Formula references, structured table ranges, and defined names aren't adjusted when row loops insert rows. Merged-cell ranges below inserted rows shift with their contents, but a merged range on a repeated row is retained only for the first generated row.

PPTX templates support placeholders, loops, conditions, tables, and images on slides. Slide masters, slide layouts, and speaker notes aren't processed.

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 document.

Delimiters

Delimiters wrap every placeholder in the Office 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, XLSX, and PPTX 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.

Image payload bytes are inspected to determine their format. For URL and data URL sources, the detected format is used instead of inferring it from response metadata, URL extension, or MIME type. When an explicit format is supplied, it must match the detected format. Raw base64 payloads require an explicit format. Payloads without a supported image signature are rejected.

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