How properties and DocProperty fields work

In this article, you will find general information about how document properties and DocProperty fields in Word work. You will learn what a document property is, what a DocProperty field is, how to open the Properties dialog box, and much more. The information applies to both custom document properties and DocProperty fields you create using Word's built-in functionality and using the Word add-in DocTools DocPropertyManager. The article also explains how you can use the built-in functionality of Word to create or edit document properties and create DocProperty fields, both via the general user interface and via macros (VBA).

As you will learn below, you can take advantage of document properties and DocProperty fields in a number of situations. This will help you produce better documents in less time.

It can be slow and tiresome to work with Word's built-in functionality when it comes to properties and DocProperty fields. The DocTools DocPropertyManager add-in makes the work much easier and faster. Custom document properties and DocProperty fields created using DocTools DocPropertyManager will work as if they had been created using Word's built-in functionality. However, DocTools DocPropertyManager makes it possible to perform several tasks that are not possible via the built-in functionality.

What is a document property in Word?

There are different types of document properties.

  • Standard document properties - can also be called built-in document properties
  • Custom document properties
  • Document library properties

All Word documents contain a set of standard document properties, e.g. Title, Author, Keywords, and Comments. These properties are used to store certain types of metadata about your document. The standard properties have fixed names that you cannot change. You can edit the value of some of the standard properties (e.g. Title, Author, Keywords and Comments) whereas others store statistics data that is updated automatically by Word and that cannot be edited, e.g. file size, when the document was last saved or printed.

In addition to the standard properties, you can create properties yourself, referred to as custom document properties. Word documents do not contain any custom document properties by default. You can add as many custom document properties as you wish. Each custom document property must be assigned a name, a data type and a value. There are four data types: TextDateNumber and Yes or No. For details about the types, see About the different data types of custom document properties below.

Document library properties are related to documents that are stored in a document library on a website or in a public folder, e.g. in relation to SharePoint. This article will not deal further with document library properties.

Back to Quick Navigation 

What can document properties be used for?

None of the document properties are visible in the document content unless you do something to insert their values in the content. This is true for both the standard and the custom document properties.

In e.g. File Explorer, you can see and search for documents with specific standard document property values. This article will concentrate on what you can use document properties for in the contents of Word documents.

You can insert the value of a document property in the document by inserting a field of the type DocProperty. Such field will show the value of the related document property - standard or custom. See How to insert a DocProperty field using the built-in functionality of Word later in this article.

In a document in which you need the same data repeatedly, e.g. a client name or a product name, it is very helpful to use custom document properties. You can insert as many DocProperty fields related to the same document property as you wish. If you change the value of that custom document property, you only need to update fields in order to reflect the new value throughout the document. This applies regardless of whether one or many DocProperty fields exist. Thereby, you can define the value once and you are sure that the same value will be shown in every single DocProperty field related to that custom document property.

There are other ways to repeat data. For example, you can bookmark text and have the contents of the bookmark repeated by inserting cross-references to the bookmark. On the DocTools DocPropertyManager page, I have explained why the use of bookmarks and cross-references is less stable than the use of custom document properties and DocProperty fields.

The use of custom document properties and DocProperty fields also make it easy make templates with flexible boilerplate text so you can reuse text across documents. For example, this is useful in templates for proposals and agreements since it makes it fast and safe to update the contents with correct names and other values in the individual documents that are created. In the template, simply insert DocProperty fields as placeholders for the relevant data. Assign neutral, descriptive values to the custom document properties in the template so it is easy for the user to see which type of information each DocProperty holds. When a user creates a new document based on the template, he/she only needs to edit the values of the custom document properties.

For an example of the use of custom document properties and DocProperty fields, see the short video on the DocTools DocPropertyManager page.

Fact list

  • A document property has a name and a value. A custom document property also has a type.
  • The value of a document property can be inserted in documents using fields of the type DocProperty.
  • You can create as many custom document properties as you want.
  • Custom document properties that have been added to a document are preserved in the document regardless of whether they are used in any DocProperty field.
  • The field code of a DocProperty field must refer to the name of the document property whose value you want to appear in the document.
  • You can repeat data in a document by inserting as many DocProperty fields referring to the same document property name as you wish.
  • You can use DocProperty fields in templates as placeholders for document-specific data. 
  • To change the value of all instances of a specific DocProperty field, edit the value of the related document property and update fields.

Back to Quick Navigation 

Document properties in a template are inherited by new documents based on the template

If you want all documents that are based on a specific template to start with special values of standard properties (e.g. Title and Company) and/or a set of custom document properties, make sure these data are set up in the template. All documents based on the template will initially inherit the document properties and their values. You can then edit the values in the individual document as appropriate afterwards.

Note that the DocTools DocPropertyManager add-in lets you import custom documents from one document to another. This makes it easy to reuse metadata between documents. The add-in also lets you export custom documents to a document for easy overview in a table. You can even edit properties directly in the table and create custom document properties based in the table data, ready for import into other documents.

Back to Quick Navigation 

How to edit the values of standard document properties

If you want to edit the value of standard document properties, you need to open the built-in Properties dialog box.

How to open the built-in Properties dialog box

In newer versions of Word, the Properties dialog box is well hidden. How to open the Properties dialog box depend on your version of Word:

Word 2010 and later versions

Select File > Info (left side of dialog box) > click the Properties drop-down > select Advanced Properties.

Word 2007

Select Office button > Prepare (left side of dialog box) > in the Document Information Panel that opens below the Ribbon in Word, click the Properties drop-down > select Advanced Properties.

TIP: You can add the Properties dialog box to the Quick Access Toolbar (QAT) for easier access. The name of the command to find in the Word Options dialog box is Advanced Document Properties. For help on how to add a command to the QAT, see How to add a command or macro to the Quick Access Toolbar.

Note that DocTools DocPropertyManager provides easy access to the Properties dialog box in case you need to edit standard document properties.

The built-in Properties dialog box

Example of the Properties dialog box showing properties for a new, blank document. The name of the document appears in the title bar of the dialog box, in this case "Document3".

As can be seen in the illustration to the left, the Properties dialog box has a number of tabs: General, Summary, Statistics, Contents, and Custom. All tabs except Custom are related to standard properties.

The Summary tab has fields that let you specify a value for each of the following standard properties:

Title
Subject
Author
Manager
Company
Category
Keywords
Comments

To edit the values:

  1. Type the values you want to assign to the individual properties. You may leave any of the fields empty.
  2. Click OK when finished.

How to create or edit custom document properties using the built-in functionality of Word

The built-in functionality of Word lets you create custom document properties via the Properties dialog box.

Once you have created a custom document property, you can edit its value but you cannot change the name. The only way to change the name of a custom document property is to delete it and create a new one. In addition, you will need to change the field code of any DocProperty field that refer to the custom document property in question. As opposed to this, the DocTools DocPropertyManager add-in lets you rename existing custom document properties and automatically apply the change to any DocProperty field that refers to the property.

How to create a custom document property using the built-in functionality

  1. Open the Properties dialog box and select the Custom tab. See How to open the built-in Properties dialog box​.
  2. Type a name in the Name field (up to 255 characters).
  3. Select a data type in the Type field (see About the different data types of custom document properties for details).
  4. Type a value in the Value field (up to 255 characters, however, the value must comply with the data type you selected).
  5. Click Add to add the property to the Properties list. If you are creating only one property, you can skip this step.
  6. Click OK when finished.
The Custom tab of the Properties dialog box

The Custom tab of the Properties dialog box lets you create custom document properties. In this example, two custom document properties have been added.

Example of property with Link to content turned on

Example of property with Link to content turned on.

Below the Name list, you will find a number of suggested names you can select from, if relevant. The result is the same as typing the name directly in the Name field.

About the Link to content check box

Note that there is a check box, Link to content, next to the Value field. Custom document properties with Link to content turned on will show a link icon to the left of the name.

If you turn on Link to content, the label Value changes to Source and the field changes to a drop-down list, showing the names of all bookmarks in the document. Select a bookmark name from the list and Word will (or rather: may...) insert the content of the bookmark if you insert a DocProperty field that refers to the custom document property in question. If the content of the bookmark is changed, the content of any DocProperty field indirectly referring to that bookmark should change too when fields are updated but that only seems to happen if you, after the bookmark change, open the Properties dialog box and click OK - and then updated fields. 

There are also other important limitations to the bookmark content shown in such DocProperty fields: Only plain text is included in the field result and only up to 255 characters no matter what is included in the bookmark. This means that you cannot use Link to content to have DocProperty fields show longer texts or non- textual content like images or tables.

Since it is doubtful how safe and/or useful it is to use this Link to content option, the DocTools DocPropertyManager add-in does not let you create custom document properties with this option turned on. If a document contains custom document properties added via the built-in Properties dialog box and if Link to content is turned on, DocTools DocPropertyManager will detect this in case you attempt to modify the property. You will then be asked whether you want to modify the property via the built-in dialog box instead.

The built-in Properties dialog box cannot be resized. This makes it impossible to see the full names and/or full values in many cases.

The dialog box for creating and editing custom document properties in the DocTools DocPropertyManager add-in is flexible and has room for longer names and values. In addition, it lets you sort the properties alphabetically. Also, a Filter field makes it fast to find a specific property in the list. When you click a property in the list, you will see information about how many DocProperty fields are found in the document that refer to that property.

How to edit a custom document property using the built-in functionality

  1. Open the Properties dialog box and select the Custom tab.
  2. In the Properties list, select the relevant property.
  3. In the Value field, edit the value and click OK.
  4. If one or more DocProperty fields in the document refer to the edited property, update fields (Ctrl+A to select all, F9 to update fields).

As mentioned above, the built-in functionality does not let you edit the name of a custom document properties. The DocTools DocPropertyManager add-in lets you edit the name of a custom document property and will automatically correct any related DocProperty fields too.

Back to Quick Navigation  

How to insert a DocProperty field using the built-in functionality of Word

Using the built-in functionality, you can insert a DocProperty field either via the Field dialog box or by typing the field code manually. Both methods are described below. Note that the DocTools DocPropertyManager add-in makes it much faster and easier to insert DocProperty fields.

How to insert a DocProperty field using the Field dialog box

  1. In the document, click where you want the DocProperty field to be inserted.
  2. Select the Insert tab.
  3. in the Text group on the Ribbon, click the Quick Parts drop-down and select Field to open the Field dialog box.
  4. In the Categories list, select either (All) or Document Information,
  5. In the Field names list, select DocProperty.
  6. In the Property list, select the name of the property whose value the DocProperty field is to show. See the illustration of the Field dialog box below.
       
    The list includes both the standard properties and custom properties, if any.
  7. Click OK to insert the DocProperty field.
The Field dialog box ready for inserting a DocProperty field

The Field dialog box ready for inserting a DocProperty field.

NOTE: By default, Preserve formatting during updates is turned on. If turned on, the MERGEFORMAT switch will be added to the field code. Personally, I always turn the option off since it may result in undesired formatting. For example, a field with the switch may appear with bold text if the field has once shown an error. If special formatting is desired, it is more stable to add relevant switches for the formatting directly.

DocProperty field showing field codes

DocProperty field showing field code and field result.

How to insert a DocProperty field by typing the field code manually

If you know the name of the document property you want to use, it is faster to type the field code manually than using the Field dialog box. The same is true for many other types of fields.

  1. In the document, click where you want the DocProperty field to be inserted.
  2. Press Ctrl+F9 to insert a pair of field brackets (cannot be typed manually).
  3. Between the field brackets, type the following field code:
       
    DOCPROPERTY "[name of property]"
       
    where you replace [name of property] with the name of the desired property.
       
    The use of uppercase and lowercase in the field code is without importance. If the property name consists of one word only, you may leave out the quotation marks. If the property name includes at least one space, you must add the quotes. Therefore, I recommend that you always add quotes for consistency.
  4. Press F9 to update the field and turn off field codes.
    If the field for some reason still shows field codes, press Alt+F9 to show the field result instead. 

If a DocProperty field refers to a property name that does not exist, the fields will show an error:

Example of DocProperty field showing an error because it refers to a property that does not exist

Example of DocProperty field showing an error because it refers to a property that does not exist.

The DocTools DocPropertyManager add-in lets you add all missing custom document properties, if any, by the click of a button.

DocProperty fields must be updated to reflect changes in the values of the related properties

Note that DocProperty fields do not update automatically. If the value of one or more properties referred to in DocProperty fields have been changed, you need to update the fields to reflect the changes.

You can update DocProperty fields manually by selecting all (Ctrl+A) and pressing F9.

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

Note that the DocTools DocPropertyManager automatically updates DocProperty fields when needed.

About the different data types of custom document properties

As mentioned above, custom document properties can be of the types Text, Date, Number and Yes or No. Below, you will find a description of each type.

Text is the most commonly used type. The other types, Date, Number and Yes or no require specific values and in the document, such fields will not always insert a value that is identical to the value you specify in the Properties dialog box. Therefore, you must make sure that you fully understand how the values of those types work before you start using them.

I use custom document properties and DocProperty fields in the main part of the many Word documents I work with. I always define custom document properties of the type Text.

Type of custom document property

Description - how it works

Text

DocProperty fields that insert a Text property, inserts precisely the text you specify as the value of the property. Most often, you can use the type Text for all DocProperty fields. The value can include max. 255 characters.

The built-in functionality only lets you enter plain text as the value, without any paragraph breaks or manual line breaks. The DocTools DocPropertyManager add-in lets you add the following characters:

  • nonbreaking spaces
  • nonbreaking hyphens
  • en dashes
  • em dashes
  • manual line breaks
  • paragraph breaks

Date

You must enter a value in a date format that matches the definition in the regional settings on your PC.

You may need to experiment since the language settings also influence the way Date properties work.

In case of a standard Danish setting, you can, for example, use the syntax dd-mm-yyyy, e.g. 31-05-2019. A DocProperty field in the document may not always show the date as it appears in the value you specify. You may instead use the type Text. This way, you can enter the date value precisely as you want it to appear in the DocProperty fields in the document.

Number

You must specify a number, either an integer or a decimal number. The decimal symbol to use depends on the regional settings on your PC. If the decimal symbol is a period you can, e.g., enter 12345.678 as a value. A DocProperty field in the document will show the specified value. You may enter a number value with a thousands separator but Word ignores the separator in the field result.

Yes or No

You may enter the following:

*   -1 (corresponds to yes) or 0 (corresponds to no) or
*   True (corresponds to yes) or false (corresponds to no)

When you insert DocProperty fields, the value in the document will only be 'Y' for yes and 'N' for no.

Managing document properties and DocProperty fields via macros (VBA)

Below, you will find VBA code examples showing:

  • How you can edit the values of standard document properties via VBA
  • How you can create and edit the values of custom document properties via VBA
  • How you can insert DocProperty fields via VBA

These code samples may help you create useful macros. The DocTools DocPropertyManager add-in lets you do much more than that.

In order to create solid VBA code, you will need to add error handling to handle the types of errors that might occur. The code sample below do not include such error handling.

Back to Quick Navigation 

How to edit the values of standard document properties via VBA

Below are examples of VBA code to edit each of the standard document properties found on the Summary tab of the Properties dialog box.

By using names from the wdBuiltInProperty enumeration, you are sure to use correct names that will work in any language version of Word. Each property also has a number that can be used but your VBA code is much easier to understand if you use the names.

For a full list of the wdBuiltInProperty enumeration for Word, see https://docs.microsoft.com/en-us/office/vba/api/word.wdbuiltinproperty. Note the comments after each of the listed properties - some are not supported in Word even if they are in the list.

Examples of VBA code for editing the values of the standard properties in the active document found on the Summary tab of the Properties dialog box:

ActiveDocument.BuiltInDocumentProperties(wdPropertyTitle) = "My Title"
ActiveDocument.BuiltInDocumentProperties(wdPropertySubject) = "My Subject"
ActiveDocument.BuiltInDocumentProperties(wdPropertyAuthor) = "My Author"
ActiveDocument.BuiltInDocumentProperties(wdPropertyManager) = "My Manager"
ActiveDocument.BuiltInDocumentProperties(wdPropertyCompany) = "My Company"
ActiveDocument.BuiltInDocumentProperties(wdPropertyCategory) = "My Category"
ActiveDocument.BuiltInDocumentProperties(wdPropertyKeywords) = "My Keywords"
ActiveDocument.BuiltInDocumentProperties(wdPropertyComments) = "My Comments"

If you are editing two or more values, you should use With and End With as shown below:

With ActiveDocument
    .BuiltInDocumentProperties(wdPropertyTitle) = "My Title"
    .BuiltInDocumentProperties(wdPropertySubject) = "My Subject"
    .BuiltInDocumentProperties(wdPropertyAuthor) = "My Author"
End With

How to create a custom document property via VBA

The VBA code below creates a custom document property in the active document, with the name "My property", link to content turned off, type "Text" and value "My property value":

ActiveDocument.CustomDocumentProperties.Add _
    name:="My property", _
    LinkToContent:=False, _
    Value:="My property value", _
    Type:=msoPropertyTypeString

The Type can be one of the following:

  • msoPropertyTypeString
    Corresponds to the type Text in the Properties dialog box > Custom tab.
  • msoPropertyTypeDate
    Corresponds to the type Date in the Properties dialog box > Custom tab.
  • msoPropertyTypeNumber or msoPropertyTypeFloat
    Corresponds to the type Number in the Properties dialog box > Custom tab.
    In case of a decimal number value, the type must be msoPropertyTypeFloat. The decimal symbol must match the decimal symbol defined in regional settings.
    In case of an integer value, the type must be msoPropertyTypeNumber.
  • msoPropertyTypeBoolean
    Corresponds to the type Yes or no in the Properties dialog box > Custom tab.

For more details about the data types, see About the different data types of custom document properties.


How to edit the value of a custom document property via VBA

The VBA code below changes the value of a custom document property named "My property" to "My new property value":

ActiveDocument.CustomDocumentProperties("My property").Value = "My new property value"

The VBA code also works if you leave out ".Value" since .Value is the default property. However, I recommend always adding the property. It makes the code easy to read and you don't run into problems.  The example below has left out the default property .Value (not recommended even if it works):

ActiveDocument.CustomDocumentProperties("My property") = "My new property value"

The new value you assign must match the type of custom document property. For example, you can only assign the value in the example above if the type of custom document property is Text. If you assign a value that does not match the type, a run-time error occurs, saying "Type mismatch".


How to insert a DocProperty field via VBA

The VBA code below inserts a DocProperty field at the selection, referring to a custom document property named "My property". If no document property with the specified name exists, the field will show an error.

If you want the MERGEFORMAT switch to be turned on for the field, change PreserveFormatting from False to True.

The double quotation marks around "My property" are needed to have quotation marks added in the field code. There are other ways of adding the quotation marks, e.g. using the character code Chr(34).  You could then replace ""My property"" with this instead:
Chr(34) & "My property" & Chr(34)

Selection.Fields.Add _
    Range:=Selection.Range, _
    Type:=wdFieldEmpty, _
    Text:="DOCPROPERTY  ""My property"" ", _
    PreserveFormatting:=False

The field code of the inserted field will look like this:

{ DOCPROPERTY "My property" }

The field result depends on the value of the property named "My property".

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 docproperty field") or something similar.

More tips about working with fields in Word

Turn on field shading so you can distinguish fields from other content

In documents with fields, it is important to be able to distinguish fields from normal text so you don't accidentally change a field result by manually modifying its result. If you manually modify a field result, the change will disappear the next time the field is updated unless the field has been locked.

Therefore, I recommend that you set the Word option for Field shading to Always (File > Options > Advanced > Show document content group > Fields shading > Always). With field shading on, all fields are shown with gray shading on the screen. The gray shading is only visible on the screen in Word - it does not print and it is not visible in PDF.

Information about how different types of fields are updated

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

Useful shortcuts

For information about keyboard shortcuts related to fields, see my article Word Fields – Useful Keyboard Shortcuts.

Back to Quick Navigation