docx recipe generates office docx reports based on the uploaded docx template with handlebars tags filled inside using Word application.

  1. Open Word and create docx file using handlebars templating engine.
  2. Upload created docx file as an asset to the jsreport studio
  3. Create template, select docx recipe and link the previously uploaded asset
  4. Attach sample input data or scripts if needed
  5. Run the template, you get back dynamically assembled docx report



Built-in helpers


Create a list with single item using Word and call the docxList helper. It will iterate over provided data and create another list item for every entry.

 - {{#docxList people}}{{name}}{{/docxList}}

Example - List


Create a table with columns header and single row using Word. Call {{#docxTable}} in the first cell of the data row and end the call {{/docxTable}} at the last cell.

columnA columnB
--- ---
{{#docxTable people}}{{name}} {{email}}{{/docxTable}}

Example - Table

Vertical table

Use helper argument vertical=true for rendering vertical table

name {{#docxTable people vertical=true}}{{name}}
email {{email}}{{/docxTable}}

Dynamic columns

The table can be fully dynamic and even nested. Use rows=[[]] and columns=[] helper arguments to render dynamic columns.

{{docxTable rows=rowsItems columns=columnsItems}}

Merged cells can be generated by passing object to rows=[[]] and columns=[] arguments. For example using this

    "rows": [
        [{ rowspan: 2, value: 'R2-1' }, 'R2-2', 'R2-3', { rowspan: 2, value: 'R2-4' }],
        [null, 'R3-2', 'R3-3', null],
        ['R4-1', 'R4-2', 'R4-3', 'R4-4'],
        ['R5-1', { colspan: 2, value: 'R5-2' }, 'R5-4']
    "columns": ['R1-1', 'R1-2', 'R1-3', 'R1-4']

will generate following table:

R1-1 R1-2 R1-3 R1-4
R2-1 R2-2 R2-3 R2-4
R3-2 R3-3
R4-1 R4-2 R4-3 R4-4
R5-1 R5-2 R5-4

It is important to note that the columns and rows array should produce same shape of cells, it means that when you use object with rowspan you have to pass null when a cell needs to be ignored as result of the rowspan layout.

The docxTable helper call provides also @rowIndex and @columnIndex variables, which can be used to generate dynamic content based on conditions using those values.

{{#docxTable rows=rowsItems columns=columnsItems}}


Wrap block with {{#docxStyle}}{{/docxStyle}} and pass textColor parameter to dynamicaly specify text color.

{{#docxStyle textColor='0000FF'}}Simple text{{/docxStyle}}

Supported attributes:

  • backgroundColor
  • textColor

Example - Style


  1. Prepare image placeholder using word - place any image to the desired position and format it to your needs.
  2. Select image, select Word tab "Insert", click on "Bookmark and create one
  3. Right click image and click "Hyperlink"
  4. Click bookmark and select previously created bookmark
  5. Click ScreenTip still on the "Insert Hyperlink" modal.
  6. Fill the docxImage helper call {{docxImage src=myDataURIForImage}}
  7. Hit ok and close the hyperlink dialog. Now if you hower the image you should see the docxImage helper call
  8. Run the template with myDataURIForImage prop in the input data and you should see the image replaced in the output.

Example - Image

docxImage supports the following configuration properties:

  • src (string) -> specifies the base64 dataURI string representation of the image to load or an url from which to fetch the image
  • usePlaceholderSize (boolean) -> when true the dimensions of the image will be set to the same dimensions than the placeholder image defined on the docx file. Ex: {{docxImage src=src usePlaceholderSize=true}}
  • width (string) -> specifies the width of the image, value can be in px or cm. when only width is set, the height will be automatically generated based on the aspect ratio of the image. Ex: {{docxImage src=src width="150px"}}
  • height (string) -> specifies the height of the image, value can be in px or cm. when only height is set, the width will be automatically generated based on the aspect ratio of the image. Ex: {{docxImage src=src height="100px"}}


Create a chart inside the desktop word application and use docxChart helper call inside the chart title.

Example - Chart

The helper call in a title can look like this:

A title{{docxChart data=fruits}}

With the following data on the input:

    "fruits": {
        "labels": ["Q1", "Q2", "Q3", "Q4"],
        "datasets": [{
            "label": "Apples",
            "data": [100,50,10,70]
        }, {
            "label": "Oranges",
            "data": [20,30,20,40]

The data.labels describes labels on the X axis. The data.datasets includes values for the Y axis.

Each dataset need to contain a label, and the data associated with it, additionally (only for scatterChart type) it can also define some labels for each specific unit of data (dataLabels)

    "fruits": {
        "labels": ["Q1", "Q2", "Q3", "Q4"],
        "datasets": [{
            "label": "Apples",
            "data": [100,50,10,70],
            "dataLabels": [
                    "value": "Medium",
                    // possible values are: "left", "right", "center", "top", "bottom"
                    "position": "left"
        }, {
            "label": "Oranges",
            "data": [20,30,20,40]

You can also pass some options to the chart that control the way the chart display, limit the information.

{{docxChart data=fruits options=options}}

the supported options are:

  • scales (object) -> Options to control the display of the chart axis
    • scales.xAxes (array) -> Options to control the display of the x axes
    • scales.yAxes (array) -> Options to control the display of the y axes Axis options
      • display (boolean) -> wheter to show or hide the axis
      • ticks.stepSize (number) -> the step size to use to separate the axis's ticks
      • ticks.min (number) -> the min value to show in the axis's ticks
      • ticks.max (number) -> the max value to show in the axis's ticks
// example options
    "scales": {
        "xAxes": [{
              "display": true,
              "ticks": {
                  "stepSize": 2,
                  "min": 1,
                  "max": 15

Automatic sync of Table of Contents

A docx document requires to always refresh the TOC to keep it in sync with the content/titles of the document. This presents an issue when you generate the content/titles of the document dynamically, because when you open the docx file you will noticed that the generated TOC is out of sync with what the document contains. To help with this we automatically update the TOC when producing the docx file, we do our best to produce the same result as you would get by refreshing manually, but sometimes it's not possible to produce the same result, just keep in mind that even if the styles don't match the TOC at least should have the same items/titles as the document.


The form elements like checkboxes and inputs can be placed to the word file from the Developers tab. This tab is by default hidden so you need to enable it using:

File tab, go to Options > Customize Ribbon Under Customize the Ribbon and under Main Tabs, select the Developer checkbox.

Text input

No need to use a special helper. Just add a text box and use handlebars syntax inside to fill a dynamic value.


Add checkbox control from the Developer tab, select Properties and use docxCheckbox helper call in the title. The only supported param is value which expects bool to toggle the checkbox.

{{docxCheckbox value=ready}}


Add combobox control from the Developer tab, select Properties and use docxCombobox helper call in the title.

{{docxCombobox value=val}}

In case your items are static, you can prepare them upfront in the "Drop-Down List Properties" and use just a single parameter value to preselect desired items.

In case your items are dynamic, you can bind them using items parameter. This parameter expects the following array: [ { value: "a", text: "Some text to select" } ...]

{{docxCombobox value=val items=items}}


Add a forced page break to the document.



Allows to insert raw xml into the document, replacing some parent xml element. Intended to be used for advanced users which know how to manipulate the raw xml representation of a docx file

{{docxRaw xml="<w:r><w:t>raw xml run</w:t></w:r>" replaceParentElement="w:r"}}

Custom helpers

You can implement also your own custom helpers and use them in the word templates. The helpers section can be toggled in the studio using the "show helpers" button.

docx helpers

Child templates

The recipe doesn't support using child templates or assets to insert another docx file into one template. Both can be used just to insert text.


Repetitive uploading of the docx template can get easily tedious. Fortunately, you can use the fs store external editor editing feature with docx as with any other file. The first you need to change the configuration to enable automatic files reload on external changes.

"extensions": {
  "fs-store": {
    "externalModificationsSync": true

Afterward, make sure you have ready a template with docx recipe and associated docx template in the studio. Then open a word application (the best is on the second screen) and find file data/adocxtemplate/content.docx representing your associated template. Now, editing and saving this file in word app cause automatic reload of the template in the studio and re-render so you see immediately the reflected changes.

Preview in studio

See general documentation for office preview in studio here.


  "template": {
    "recipe": "docx",
    "engine": "handlebars",
    "docx": {
       "templateAssetShortid": "xxxx"
  "data": {}

In case you don't have the office template stored as an asset you can send it directly in the API call.

  "template": {
    "recipe": "docx",
    "engine": "handlebars",
    "docx": {
       "templateAsset": {
          "content": "base64 encoded word file",
          "encoding": "base64"
  "data": {}

jsreport version