docxRendererLast updated on
Last updated on
Render OpenForm artifacts to Word documents
Render forms to DOCX (Word) documents using template placeholders. Built on docx-templates, supporting Handlebars-style syntax with automatic field serialization.
Example
import { open } from '@open-form/core'
import { docxRenderer } from '@open-form/renderer-docx'
const form = open.form({
name: 'contract',
fields: {
clientName: { type: 'text', label: 'Client Name' },
contractValue: { type: 'money', label: 'Contract Value' },
startDate: { type: 'date', label: 'Start Date' }
},
layers: {
docx: {
kind: 'file',
mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
path: '/templates/contract-template.docx'
}
},
defaultLayer: 'docx'
})
// Fill the form with data
const filled = form.fill({
fields: {
clientName: 'Acme Corp',
contractValue: { amount: 50000, currency: 'USD' },
startDate: '2024-04-01'
}
})
// Render the filled form
const output = await filled.render({
renderer: docxRenderer()
})
// output is Uint8Array - write to file
fs.writeFileSync('contract-filled.docx', output)Import
From the umbrella package:
import { docxRenderer } from '@open-form/renderers'Or from the individual package:
import { docxRenderer } from '@open-form/renderer-docx'API
docxRenderer()
Factory function that creates a configured DOCX renderer instance.
function docxRenderer(options?: DocxRendererOptions): OpenFormRenderer<
RendererLayer & { type: 'docx'; content: Uint8Array },
Uint8Array
>Parameters
options?: DocxRendererOptions
Configuration options
DocxRendererOptions
serializers?: SerializerRegistry
Custom serializer registry for formatting field values. Defaults to USA serializers.
signatureOptions?: DocxSignatureOptions
Options for signature and initials template marker rendering.
DocxSignatureOptions
placeholder?: { signature?: string | Function, initials?: string | Function }
Placeholder text/function for unsigned signatures and initials.
captured?: { signature?: string | Function, initials?: string | Function }
Text/function for captured signatures and initials.
Returns
Returns an OpenFormRenderer object with:
id: "docx"
Renderer identifier
Methods
render: (request: RenderRequest) => Promise<Uint8Array>
Async render function that returns the filled document
renderDocx()
Low-level function for direct DOCX rendering without the full renderer interface.
async function renderDocx(options: RenderDocxOptions): Promise<Uint8Array>RenderDocxOptions
template: Uint8Array
DOCX template file as binary data
data: Record<string, unknown>
Data object to populate the template
form?: Form
Form schema for automatic field type detection and serialization
serializers?: SerializerRegistry
Custom serializer registry. Defaults to USA serializers.
bindings?: Bindings
Mapping from template placeholders to data keys
signatureOptions?: DocxSignatureOptions
Options for signature and initials rendering
options?: DocxRenderOptions
DOCX-specific rendering options
DocxRenderOptions
cmdDelimiter?: [string, string]
Custom command delimiter. Defaults to ["{{", "}}"]
failFast?: boolean
Fail immediately on errors. Defaults to false.
processLineBreaks?: boolean
Convert newlines to line breaks. Defaults to true.
Returns
Returns a Promise<Uint8Array> containing the rendered DOCX document.
Template Syntax
DOCX templates use Handlebars-style placeholders:
Contract for {{clientName}}
Total Value: {{contractValue}}
Start Date: {{startDate}}
{{#if hasDiscount}}
Discount Applied: {{discountPercent}}
{{/if}}Supported Features
| Syntax | Description |
|---|---|
{{fieldName}} | Simple value insertion |
{{#if condition}}...{{/if}} | Conditional sections |
{{#each items}}...{{/each}} | Loop over arrays |
{{#unless condition}}...{{/unless}} | Negative conditionals |
Automatic Serialization
When a form schema is provided, field values are automatically serialized:
// Money fields formatted as "$50,000.00"
// Date fields formatted as "April 1, 2024"
// Phone fields formatted as "(555) 123-4567"Custom Serializers
Use custom serializers for different locales:
import { renderDocx } from '@open-form/renderer-docx'
import { euSerializers } from '@open-form/serialization'
const output = await renderDocx({
template: templateBytes,
data,
form,
serializers: euSerializers,
})
// Money formatted as "50.000,00 €" instead of "$50,000.00"Template Bindings
Map template placeholders to different field names:
const form = open.form({
name: 'contract',
fields: {
clientFullName: { type: 'text' }
},
layers: {
docx: {
kind: 'file',
mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
path: '/templates/contract.docx',
bindings: {
client_name: 'clientFullName' // Maps {{client_name}} to clientFullName field
}
}
}
})Related
- Renderers - Renderer interface overview
- Serialization - Value formatting