Fields and cross-references

Word fields contain an instruction and an optional saved result. The editor preserves both forms when it opens and saves a DOCX file.

The editor evaluates a defined set of display-only fields. It never runs macros, DDE instructions, or external include instructions.

Show field codes

Press Option+F9 on macOS or Alt+F9 on Windows to show field instructions. Some Mac keyboards require Fn+Option+F9. Press the shortcut again to return to field results.

The shortcut changes the display without changing document content or adding an undo step. It covers cross-references, form fields, and generated tables of contents, including fields in tables, notes, headers, and footers. Field instructions remain inert. Toggle back to field results before editing a form value.

Supported fields

The editor also renders saved results for other complex and simple fields. Unsupported instructions keep their saved result.

Leading direction marks remain in saved results. Their formatting does not replace the first visible result run’s formatting. A result containing only direction marks keeps its first run’s formatting.

Wrapped field results

Saved field results can wrap across lines. Long unbroken results, including hyperlink URLs, can break at the line edge. Authored line breaks inside supported results start another line. Page breaks follow the surrounding story rules. Page breaks inside table cells do not add pages.

Wrapping does not split an atomic field into separately editable characters, unless you edit saved field results. The caret before the field stays on its first line. The caret after it goes to its last line. Deleting the field removes the complete field.

Breaking long unbroken results excludes page-number placeholders, PAGEREF results, form controls, note marks, and positional tabs. These items retain their existing layout limits. Text form fields have separate editing rules described later in this guide.

Nested fields

Saved results inside another field's instruction do not add text, line breaks, or links. Find and text reads skip them too. This applies to complex fields and simple fields (w:fldSimple). The outer field keeps its normal display behavior. Fields inside a saved result still display.

Edit saved field results

By default, these saved field results behave as one unit. Typing beside a field places text before or after it. Legacy text form fields have separate editing rules.

Caret positions and selections retain both field boundaries, including paragraphs that contain only fields. Computed field caches remain read-only.

To let readers edit the saved result of a field, set fieldResults to 'editable' when you create the editor:

import { createDocxEditor } from '@docx-editor.dev/core';

const editor = createDocxEditor({
  container,
  document: bytes,
  fieldResults: 'editable',
});

The same setting works on the packaged editor and DocxEditor.Root in React and Vue. Set it when the editor starts. Later prop changes have no effect and produce a development warning.

import { DocxEditor } from '@docx-editor.dev/react';

export function FieldEditor({ bytes }: { bytes: Uint8Array }) {
  return <DocxEditor document={bytes} fieldResults="editable" />;
}

<script setup lang="ts">
import { DocxEditor } from '@docx-editor.dev/vue';

defineProps<{ bytes: Uint8Array }>();
</script>

<template>
  <DocxEditor :document="bytes" field-results="editable" />
</template>

This mode applies to fields that show their saved result: DATE, TIME, CREATEDATE, SAVEDATE, PRINTDATE, MERGEFIELD, HYPERLINK, QUOTE, FILENAME, FILLIN, and SEQ. Fields that the editor computes, such as PAGE, NUMPAGES, REF, PAGEREF, and DOCPROPERTY, stay one unit. Editable mode supports saved results without nested fields. A simple field (w:fldSimple) inside a complex field result is not supported. Do not enable editable mode for documents with this structure. Other nested results keep their existing addressing behavior.

In this mode:

• Typing, deletion, formatting, and composed input inside a result change the result text. Undo and redo treat a typing burst as one step.
• Text typed at the start or end of a result goes before or after the field.
• Backspace after a field, or Delete before it, selects the whole field. Press the key again to remove the field.
• A selection with one end inside a result and the other end outside grows to cover the whole field.
• Deleting only the result text keeps the field with an empty result. The empty field is one unit: text typed beside it goes before or after it, and Backspace or Delete next to it removes it.
• In suggesting mode, edits inside a result are tracked inside the result.
• A w:fldSimple field becomes the equivalent complex field when you edit its result.

The editor saves manual changes as field result text. It does not calculate these fields or mark them for update (w:dirty).

An application that updates fields later can replace manual changes. HYPERLINK display text and locked fields are exceptions.

Collaboration sessions keep every field one unit. If you set fieldResults: 'editable' and register a collaboration module, createDocxEditor throws a TypeError.

Keep low-level offsets consistent

For a custom core integration, use the same FieldResultsMode for layout, paragraphTextOf(), and edits. Pass fieldResults to layout options and each transaction or edit option. The modes produce different text offsets. Recompute ranges and selection offsets if you change modes.

Table of contents boundaries

Generated TOC rows are read-only. Ordinary text before or after the field remains editable, even when it shares a paragraph with a field marker. Formatting a selection that includes a TOC, such as Select All followed by a highlight, formats the ordinary text and leaves the generated rows unchanged. The TOC highlight follows the generated content. TOC links use the TOC paragraph formatting and explicit run formatting, as in Word. The Hyperlink character style does not add blue underlines inside generated TOC results.

Character-style header fields

Header STYLEREF fields use text with the named character style applied directly. A derived style does not match its base style. Use the style's display name, not its internal identifier.

The default result uses the first occurrence on the page. The \l switch uses the last occurrence. A page without a match uses the last preceding occurrence. If none precedes it, the result uses the first following occurrence.

Visible body text supplies these results. Hidden text and field instructions do not supply results. Revision display settings control which inserted and deleted text supplies results.

Header height adjusts for each page's result. Body text and footnotes use the space left by that header. During pagination, each page retains the largest space that its live header needs. The displayed header keeps its current result and height. Saved results do not establish this reserved space.

A continuous section keeps the preceding section's header on their shared page. Its own header does not enlarge that page's body inset. Exact negative top margins do not reserve header height.

The \* MERGEFORMAT switch is supported. Other switches, missing matches, nested result fields, and results longer than 4,096 characters keep their saved results. Body and footer STYLEREF fields keep their saved results. Paragraph styles and style aliases are not supported.

The layout checks bounded document scans and pagination passes. Exceeded scan or pagination bounds stop layout with an error. Save preserves instructions and saved results.

REF fields

REF resolves bookmark text and numbered paragraph references. The editor supports the \r, \w, \n, \t, \h, and \* MERGEFORMAT switches.

The \t switch removes text that is not a number delimiter from a referenced number. It needs \r, \w, or \n. With \h, clicking the result follows its bookmark within the document.

The editor checks a non-empty saved result once. A matching result enables live updates after later edits. A mismatch keeps Word's saved result for that field.

An empty saved result remains eligible for live updates.

The editor also keeps the saved result for missing bookmarks, bullet targets, and unsupported switches. Bookmark text resolution stops at the target paragraph boundary.

The \r switch uses the same full-context number as \w. It does not calculate Word's relative number.

Live REF resolution covers the document body, footnotes, and endnotes. Header, footer, and text-box results keep their saved values.

NOTEREF fields

NOTEREF resolves the display number of a bookmarked footnote or endnote reference. It honors section number formats and eachSect restarts.

The editor keeps the saved result for \p, \f, eachPage restarts, and custom note marks. With \h, clicking the result follows the bookmarked note reference.

Cross-reference navigation

REF, PAGEREF, and NOTEREF fields with \h link to their bookmarks. This works for complex fields and w:fldSimple, including instructions split across runs. Missing bookmarks do not navigate. References without \h remain ordinary field results.

Navigation also works with saved results, including the \p above/below form. This does not change which field values the editor evaluates. An enclosing explicit hyperlink keeps its own target.

AUTONUM fields

Each AUTONUM field kind has its own sequence. The editor numbers each sequence in document order.

Word can restart these counters by heading context. The editor does not apply that restart behavior.

The \* switch supports Arabic, alphabetic, Roman, ordinal, cardinal text, ordinal text, and hexadecimal formats. The \e switch removes the trailing period.

An unsupported switch produces no generated value. Save does not add result runs because Word does not store results for these fields.

Save-time refresh

save() updates calibrated, writable REF and NOTEREF results in the body, footnotes, and endnotes. It commits all updated parts in one undo step.

The editor skips locked fields, revision markup, nested or unsafe result structures, and protected content controls. A skipped field keeps its saved result.

View mode and read-only sessions do not rewrite results. A collaborative session also exports the saved results without rewriting them.

Fields that stay inert

DATE, TIME, FILENAME, SEQ, LISTNUM, EQ, CITATION, and BIBLIOGRAPHY do not calculate a new value. The editor displays a saved result when one exists.

The editor preserves field instructions through save. It does not execute macros, DDE instructions, OLE content, or external include instructions.

Legacy text form fields

Select a FORMTEXT field, then double-click it or choose Edit field… from the context menu. Set its default value, type (regular text, number, or date), maximum length, format, and Fill-in enabled setting. A maximum length of zero means unlimited. React and Vue share the same default behavior.

Edit an unprotected field

Partial edits keep the field definition; replacing its whole result removes it. Typing at the end of the field inserts ordinary text after it, including at the end of a paragraph.

Deleting a word from a field boundary removes the complete field. Backspace at the end, or Delete at the start, first selects the field. Press again to remove it. Shift+Backspace follows the same behavior as Backspace.

Fill a protected field

Use Review > Protect Document for Forms to enable forms protection. Filling a protected field keeps its definition. Tab and Shift+Tab move between enabled text fields.

Protected fields validate and format input when you leave. Pasted text is limited to the remaining capacity. Invalid numbers or dates open an alert; acknowledging it clears the input, which can be restored with Undo.

Save also validates pending protected field input and applies its format. Invalid input rejects the save with code invalidArgs. The input stays available for correction, and save does not open an alert.

Use popups.textFormField for Field Options and popups.invalidTextFormField for the validation alert. See Customize popups.

Date input and UI language

locale controls date input; i18n controls UI strings. For Polish dates with the default English UI, use:

<DocxEditor document={bytes} locale="pl-PL" />

With pl-PL, 01.02.2030 means February 1. The default en-US interprets 01/02/2030 as January 2. ISO input (2030-02-01) works in every locale. Each field's format controls its displayed result. Changing locale preserves existing dates and applies to subsequent edits.

Date input supports Gregorian numeric dates, regional digits, and full English month names. Localized month names and non-Gregorian dates are not supported.

Only plain text results and the dialog's listed types and formats support editing and protected filling. The editor preserves other field structures.

Legacy checkbox form fields

A legacy checkbox (FORMCHECKBOX) uses the field's saved size. Its pointer target is at least 24 CSS pixels without changing the document layout.

Click the checkbox or press Space to toggle it. Tab moves focus between checkboxes. A toggle changes only w:checked. Disabled fields, viewing mode, and comments-only protection refuse changes.

You can toggle these fields in edit mode or with forms protection enabled. Word requires forms protection.

Legacy dropdown form fields

Legacy dropdown form fields (FORMDROPDOWN) use a native select. Click the value or focus it with Tab to choose a declared entry. Each choice updates the displayed text and saved selection in one undo step. Disabled fields and viewing or suggesting mode refuse changes. Forms protection permits filling.

For customizable list popups, use content controls.

Form field accessibility and macros

A field's w:name supplies its accessible name as bounded plain text. Fields with entry or exit macro references supply no name through this path. Macro values are not read. Entry and exit macros never run.

Mixed-script cached field results

Cached atomic field results can contain Latin and East Asian text. The layout selects the declared East Asian font for eligible display runs. All display slices keep the field's original model range. Navigation spans and explicit measurement reservations keep their existing behavior. Canonical field data and calculation support retain their existing behavior.

Next steps

• Headers and footers: Add page-number fields.
• Loading and saving: Save updated field results.
• Word fidelity: Review field support status.