Templates and fields

Suppose a client name appears three times in an agreement. Your application needs to update all three without searching for the old name or changing unrelated text.

A content control marks a region of the document and gives it metadata your application can find. In these guides, a template field is a content control used for a value or clause. It stays part of the DOCX, whether you use built-in controls or a custom UI.

Start with Fill a DOCX template. Its prepared agreement lets you change one client name and see all three occurrences update. You do not need to create fields or build a custom toolbar first.

Choose a workflow

Fill a DOCX template

Update prepared fields from application data and export the result.

Add fields to a DOCX template

Turn selected content into tagged inline and block-level fields.

Replace clauses from your application

Use tagged block-level fields as application-managed clause slots.

Lock template fields

Keep a field, its contents, or both from being changed during normal DOCX editing.

Choose what the region holds

Three content-control shapes

InlinePart of a paragraphRepeated values and typed inputs

Block-levelParagraphs or tablesClause slots and document sections

Repeating sectionA collection of itemsLine items and repeated records

Start with text fields. Add other controls when the document needs them:

Typed inputs: Use text, checkbox, date, and choice controls for values with known input behavior.
Repeating records: Add, clone, and remove repeating-section items for lists such as line items or questionnaire responses.
Custom field UI: Build a field list, navigation panel, or workflow around the controls in the open document.

Use the Document API reference for the complete operation set. Use custom content-control UI to connect document selection and navigation to your application.

Identify a control

Use a tag as the application lookup key. The alias gives people a readable title, while the ID identifies one occurrence inside the document.

Word property	SuperDoc value	Use it for
Tag	`properties.tag`	Connect one application field to every matching control. Multiple controls can share a tag.
Title	`properties.alias`	Show a human-readable field name in Word or your application UI.
ID	`id`	Address one occurrence of the field in the DOCX.

A shared tag groups controls for lookup. It does not synchronize their content. Your application decides how values flow between its data and each document occurrence.

Content controls are stored as w:sdt elements in the DOCX. You do not need to edit that XML to use the Document API.

Update metadata

Use doc.contentControls.patch({ target, alias: 'Client name' }) to update a control's title.

In V2, contentControls.patch does not support placeholder or showingPlaceholder. If either field is defined, including an empty string, null, or false, the operation returns success: false with failure.code: 'CAPABILITY_UNAVAILABLE'. The entire patch is rejected, including other fields in the same call. Omit these fields when updating supported metadata.

Changing the alias does not replace the control's visible text. Placeholder metadata also does not archive the original formatted content for later restoration. For workflows that capture and restore selected runs, see selection OOXML.