w:instrText (Field Instruction Text)

Contains the instruction string (e.g., 'TOC \o 1-3') for a complex field between begin and end fldChar elements.

Parent elements

Description

w:instrText carries the instruction text of a complex field (between the begin and separate w:fldChar markers). It is defined in ECMA-376 Part 1 §17.16.23.

The field instruction text uses the same syntax as simple field instructions (e.g. PAGE, DATE \@ "d MMMM yyyy", TOC \o "1-3" \h). Use xml:space="preserve" to ensure leading/trailing spaces in the instruction are not stripped by XML parsers.

Attributes

Attribute	Type	Possible Values	Description
`xml:space`	XML standard	`preserve`	Preserves surrounding whitespace in the instruction text. Always recommended.

Examples

<w:r>
  <w:instrText xml:space="preserve"> DATE \@ "d MMMM yyyy" </w:instrText>
</w:r>

new Run(
  new FieldCode(@" DATE \@ ""d MMMM yyyy"" ")
  { Space = SpaceProcessingModeValues.Preserve });

<!-- Table of Contents field instruction -->
<w:r>
  <w:rPr><w:vanish/></w:rPr>
  <w:instrText xml:space="preserve"> TOC \o "1-3" \h </w:instrText>
</w:r>

<!-- Page reference field -->
<w:r>
  <w:rPr><w:vanish/></w:rPr>
  <w:instrText xml:space="preserve"> REF MyBookmark \* MERGEFORMAT </w:instrText>
</w:r>

// TOC field (hidden)
new Run(
  new RunProperties(new Vanish()),
  new FieldCode(@" TOC \o ""1-3"" \h ")
  { Space = SpaceProcessingModeValues.Preserve });

// Bookmark reference field (hidden)
new Run(
  new RunProperties(new Vanish()),
  new FieldCode(@" REF MyBookmark \* MERGEFORMAT ")
  { Space = SpaceProcessingModeValues.Preserve });

<!-- MERGEFIELD instruction for mail merge -->
<w:fldChar w:fldCharType="begin"/>
<w:r>
  <w:rPr><w:vanish/></w:rPr>
  <w:instrText xml:space="preserve"> MERGEFIELD "CustomerName" \* MERGEFORMAT </w:instrText>
</w:r>
<w:fldChar w:fldCharType="separate"/>
<w:r><w:t>«CustomerName»</w:t></w:r>
<w:fldChar w:fldCharType="end"/>

new FieldCode(@" MERGEFIELD ""CustomerName"" \* MERGEFORMAT ")
{ Space = SpaceProcessingModeValues.Preserve };

Common Field Instructions

Field Type	Instruction Syntax	Purpose	Example
PAGE	`PAGE`	Current page number	` PAGE `
NUMPAGES	`NUMPAGES`	Total page count	` NUMPAGES `
DATE	`DATE \@ "format"`	Date with format	` DATE \@ “d MMMM yyyy” `
TIME	`TIME \@ "format"`	Time with format	` TIME \@ “HH:mm:ss” `
TOC	`TOC \o "1-3" \h`	Table of contents	` TOC \o “1-3” \h `
REF	`REF bookmark \* format`	Bookmark reference	` REF MyBookmark `
MERGEFIELD	`MERGEFIELD "field name"`	Mail merge field	` MERGEFIELD “CustomerName” `
IF	`IF condition value_true value_false`	Conditional	` IF “{NUMPAGES}” “>” “10” “Big” “Small” `
STYLEREF	`STYLEREF StyleName`	First heading of style	` STYLEREF “Heading 1” `
TITLE	`TITLE`	Document title	` TITLE `

Notes

Complex Field Structure: w:instrText is used only in complex fields (with begin/separate/end w:fldChar markers); simple fields use w:fldSimple instead.
Whitespace Preservation: Always use xml:space="preserve" to maintain spacing around the instruction; missing spaces can break field parsing.
Hidden Instruction: Runs carrying w:instrText typically have w:vanish in w:rPr to hide the raw instruction from display (only the result shows).
Instruction Syntax: Field instructions follow Word field code syntax (not identical to OpenXml syntax); they use backslash-prefixed switches (e.g., \@, \*, \o).
Multiple Runs: Complex fields can span multiple runs; each run may carry part of the instruction in w:instrText, or separate runs carry different field code parts.
Field Results: The cached result of a complex field is displayed between separate and end w:fldChar markers; it can contain paragraphs, tables, or other block elements.
Updateable Fields: Unlike w:fldSimple, complex fields are updateable; applications can refresh the result by re-evaluating the instruction.
Performance: Fields with complex logic (deeply nested IF statements, cross-document references) can impact performance; use sparingly in large documents.
Accessibility: Field instructions are not displayed but may affect accessibility; ensure field results are meaningful for screen readers.
Locale: Some field formats (e.g., date) are locale-sensitive; the document’s language setting affects interpretation.