How cross-reference fields in Word work

Below, you will find general information about how cross-reference fields in Word work. The information applies to both cross-references you insert using Word's built-in functionality and using the add-in DocTools CrossReferenceManager.

The DocTools CrossReferenceManager add-in makes it easier and faster to work with cross-references in Word than using the built-in functionality. However, cross-references you have inserted in a document using DocTools CrossReferenceManager work precisely as if they had been inserted using Word's built-in functionality.

What is a cross-reference in Word?

A cross-reference in Word is a field, i.e. set of codes that instructs Word to automatically insert material into a document. The material inserted by cross-reference fields can be text, section numbers, paragraph numbers, caption numbers, caption labels, etc. The field code can also include special information (referred to as switches) that make the field act or look in a special way, e.g. the field may function as a hyperlink.

As opposed to references you type manually, the great advantage of using cross-reference fields is that you only need to update fields to have the cross-references corrected if you have made changes to the document.

How to insert a cross-reference in Word?

Note that you can only insert cross-references to content that already exits in the document. For example, you cannot insert a cross-reference to a heading that has not yet been added to the document. In case you want to refer to something in another document, you can create a hyperlink.
The purpose of the article is not to go into detail about how to insert cross-references in Word but to explain how cross-references work. For completeness, here are the steps to follow to insert a cross-reference using the built-in functionality of Word:

  1. In your document, position the insertion point where the cross-reference is to be inserted.
  2. In the Ribbon, select References tab > Captions group: Cross-references.
    Note that you will also find the command in Insert tab > Links group: Cross-references.

    The following takes place in the Cross-reference dialog box. See the illustration below.
  3. In the Reference type list, select the type you want.

    You can select from: Numbered item, Heading, Bookmark, Footnote, Endnote plus caption types depending on which caption labels are available (e.g. Figure, Table, Equation). Note that the dialog box shows all types no matter whether there are any targets of the different types in your document.
  4. In the Insert reference to list, select what type of content you want the cross-reference to show.

    The items in the list depend on what you selected as the reference type in step 3.
  5. Turn on Insert as hyperlink if you want the cross-reference field to function as a hyperlink so users can click or Ctrl-click it to jump to the target.
  6. In the For which list, select the item the cross-reference must refer to.
    The list is empty if no items match the reference type you selected.
  7. Click Insert.
The built-in Cross-reference dialog box that lets you insert cross-references in Word.

The built-in Cross-reference dialog box that lets you insert cross-references in Word.

When you have clicked Insert in the Cross-reference dialog box, a cross-reference field is inserted in your document. Note that you must update cross-references yourself if you make changes to the document that influence the cross-reference targets.

The procedure above includes the main steps needed for most cross-references. In the Cross-reference dialog box, the Separate numbers with and Include above/below check boxes are enabled under some conditions. They are used for special purposes and are not covered here.

If you want to insert cross-reference constructions like "See Section 1.2, "This is the title", page 14", you will need to type the surrounding text and repeat the steps above three times because you need a cross-reference to three items: The paragraph number (1.2 in the example), the paragraph text ("This is the title" in the example) and the page number (14 in the example). On the other hand, the DocTools CrossReferenceManager add-in lets you insert entire cross-reference constructions like "See Section 1.2, "This is the title", page 14" in a single operation.

Are there different types of cross-reference fields?

Let's look a bit closer into the cross-reference fields. When you insert a cross-reference, the field code inside the field will depend on what the reference refers to. There are three types of cross-reference fields in Word. The first part of the field code of a cross-reference field tells which type of field it is. The field type can be one of the following:

  • REF
  • PAGEREF
  • NOTEREF

You can read more about the syntax later in this article.
Below, you can read about how the three types of cross-references work.

Type of field

Description

PAGEREF

A cross-reference field that directly or relatively refers to the page on which the target is found is of the type PAGEREF. When you select “Page number” as the “Reference to insert” in the built-in Cross-reference dialog box in Word or in the Insert Cross-reference dialog box in DocTools CrossReferenceManager, the inserted cross-reference field will be of the type PAGEREF. Also, the custom text placeholders {P} and {P_a/b} that can be used in DocTools CrossReferenceManager will insert PAGEREF fields.

NOTEREF

A cross-reference field with a footnote or an endnote as the target will be of the type NOTEREF.

REF

All other cross-reference fields will be of the type REF.

How does a cross-reference field know which content to show?

In order for a cross-reference field to show the correct content, it must include information that makes this possible – and that is precisely what it does. The field code inside a cross-reference field refers to a bookmark that points out the target

A bookmark in Word is a named location or a named block of text or other content in a document.

The field code inside a cross-reference field includes a reference to a bookmark that acts as the target of the cross-reference. See the illustration below.

If you use the built-in functionality in Word for inserting e.g. a cross-reference to a heading, Word automatically adds a bookmark around the heading text, excluding the paragraph mark, if such bookmark is not already found. The name of the bookmark is included in the field code of the cross-reference field. Such automatically added bookmarks are named _Ref followed by eight or nine digits.

When inserting a cross-reference to a caption, a bookmark will also be used to enclose the part of the caption content that is to be displayed by the cross-reference field. The bookmark will enclose different parts of the caption depending on the kind of caption reference you select (e.g. the entire caption or only the label and number).

Example of cross-reference bookmark name

_Ref123456789

The underscore in start of the bookmark name results in the bookmark being handled as a hidden bookmark in Word. You cannot add hidden bookmarks manually, i.e. the built-in Bookmark dialog box doesn’t let you start a bookmark name with “_”.

Hidden bookmarks remain invisible on the screen even if you turn on display of bookmarks. In the Bookmarks dialog box, you must turn on Hidden bookmarks to have the hidden bookmarks listed in the dialog box.

Note that names of bookmarks added by DocTools CrossReferenceManager follow the same syntax rules as the bookmarks added by the built-in cross-reference functionality.

Cross-reference field in Word showing field result and field code

Example of cross-reference field of the type REF showing the field result and the field code. In this example, the h switch is included which means that the field works as a hyperlink so that you go to the bookmarked target when clicking or Ctrl-clicking the field (depending on your Word settings).

Cross-reference fields in Word - Bookmark dialog box showing REF bookmark

The Bookmark dialog box showing the related _Ref bookmark.

What is the syntax of the field code in cross-reference fields of the types REF, PAGEREF and NOTEREF?

REF field code syntax

The syntax for REF fields is:

{ [REF] Bookmark [\* Format Switch ] [Switches ] }

The format switch and switches parts are optional.

Examples:

Field code examples - REF field

PAGEREF field code syntax

The syntax for PAGEREF fields is:
{ PAGEREF Bookmark [\* Format Switch ] [Switches ]}
The format switch and switches parts are optional.

Examples:

Field code examples - PAGEREF field

NOTEREF field code syntax

The syntax for NOTEREF fields is:
{ NOTEREF Bookmark [\* Format Switch ] [Switches ]}
The format switch and switches parts are optional.

Examples:

Field code examples - NOTEREF field

How to find information about the field switches?

In the general help on Word, you can find information about the different types of switches that can be used with specific fields.

The fastest way to find this information is often to search using your preferred browser. You can search for "field codes [TYPE OF FIELD] field" (example: "field codes ref field") or something similar. You will find a full list covering all field types in the Microsoft article List of field codes in Word.

Are cross-references updated automatically?

Note that cross-references do not update automatically. If cross-references refer to headings, bookmarks, numbers or other targets that have been changed, you need to update the fields to reflect the changes.

You can update cross-references manually by selecting all (Ctrl+A) and pressing F9. Cross-references will also be updated when you switch to Print Preview or when you print if the Word option File > Options > Display > Printing options: Update fields before printing is turned on.

For detailed information about how all types of fields are updated, see my article Updating Fields in Word – How it Works.

How to fix broken cross-references that do not show the correct content?

You may experience that one or more cross-reference fields in a document do not show the expected content even if you have updated fields.

For example, you may experience problems of the following types:

  • A cross-reference is missing part of the text it should have shown
  • A cross-reference to a numbered heading shows 0 instead of the expected number or shows a wrong number
  • A cross-reference includes more text than expected
  • A cross-reference shows an error, telling that the reference source is not found.

If you run into such problems, my article Cross-reference Problems – Troubleshooting on my website thedoctools.com can help you understand the cause of the problems and help you solve them. The article includes videos that illustrate what causes the problems and how to solve them.

Note that my add-in DocTools CrossReferenceManager can help you automatically find and fix cross-reference problems. It can even prevent some of the problems from occurring.