Add Content controls to Word documents

Article
03/10/2023

In document-level Word projects, you can add content controls to the document in your project at design time or at run time. In Word VSTO Add-in projects, you can add content controls to any open document at run time.

Applies to: The information in this topic applies to document-level projects and VSTO Add-in projects for Word. For more information, see Features available by Office application and project type.

This topic describes the following tasks:

Add content controls at design time
Add content controls at run time in a document-level project
Add content controls at run time in a VSTO Add-in project

For information about content controls, see Content controls.

Add Content controls at design time

There are several ways to add content controls to the document in a document-level project at design time:

Add a content control from the Word Controls tab of the Toolbox.
Add a content control to your document in the same manner you would add a native content control in Word.
Drag a content control to your document from the Data Sources window. This is useful when you want to bind the control to data when the control is created. For more information, see How to: Populate documents with data from objects and How to: Populate documents with data from a database.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Personalize the IDE.

To add a content control to a document by using the Toolbox

In the document that is hosted in the Visual Studio designer, put the cursor where you want to add the content control, or select the text that you want the content control to replace.
Open the Toolbox and click the Word Controls tab.
Add the control one of the following ways:
- Double-click a content control in the Toolbox.
  
  or
- Click a content control in the Toolbox and then press the Enter key.
  
  or
- Drag a content control from the Toolbox to the document. The content control is added at the current selection in the document, not at the location of the mouse pointer.

Note

You cannot add a GroupContentControl by using the Toolbox. You can only add a GroupContentControl in Word, or at run time.

Note

Visual Studio does not provide a check box content control in the Toolbox. To add a check box content control to the document, you must create a ContentControl object programmatically. For more information, see Content controls.

To add a content control to a document in Word

In the document that is hosted in the Visual Studio designer, put the cursor where you want to add the content control, or select the text that you want the content control to replace.
On the Ribbon, click the Developer tab.

Note

If the Developer tab is not visible, you must first show it. For more information, see How to: Show the Developer tab on the Ribbon.
In the Controls group, click the icon for the content control that you want to add.

Add content controls at run time in a document-level project

You can add content controls programmatically to your document at run time by using methods of the Controls property of the ThisDocument class in your project. Each method has three overloads that you can use to add a content control in the following ways:

Add a control at the current selection.
Add a control at a specified range.
Add a control that is based on a native content control in the document.

Dynamically created content controls are not persisted in the document when the document is closed. However, a native content control remains in the document. You can recreate a content control that is based on a native content control the next time the document is opened. For more information, see Add controls to Office documents at run time.

Note

To add a check box content control to a document in a Word 2010 project, you must create a ContentControl object. For more information, see Content controls.

To add a content control at the current selection

Use a ControlCollection method that has the name Add<control class> (where control class is the class name of the content control that you want to add, such as AddRichTextContentControl), and that has a single parameter for the name of the new control.

The following code example uses the AddRichTextContentControl method to add a new RichTextContentControl to the beginning of the document. To run this code, add the code to the ThisDocument class in your project, and call the AddRichTextControlAtSelection method from the ThisDocument_Startup event handler.

private Microsoft.Office.Tools.Word.RichTextContentControl richTextControl1;

private void AddRichTextControlAtSelection()
{
    this.Paragraphs[1].Range.InsertParagraphBefore();
    this.Paragraphs[1].Range.Select();

    richTextControl1 = this.Controls.AddRichTextContentControl("richTextControl1");
    richTextControl1.PlaceholderText = "Enter your first name";
}

Dim richTextControl1 As Microsoft.Office.Tools.Word.RichTextContentControl

Private Sub AddRichTextControlAtSelection()
    Me.Paragraphs(1).Range.InsertParagraphBefore()
    Me.Paragraphs(1).Range.Select()
    richTextControl1 = Me.Controls.AddRichTextContentControl("richTextControl1")
    richTextControl1.PlaceholderText = "Enter your first name"
End Sub

To add a content control at a specified range

Use a ControlCollection method that has the name Add<control class> (where control class is the name of the content control class that you want to add, such as AddRichTextContentControl), and that has a Range parameter.

The following code example uses the AddRichTextContentControl method to add a new RichTextContentControl to the beginning of the document. To run this code, add the code to the ThisDocument class in your project, and call the AddRichTextControlAtRange method from the ThisDocument_Startup event handler.

private Microsoft.Office.Tools.Word.RichTextContentControl richTextControl2;

private void AddRichTextControlAtRange()
{
    this.Paragraphs[1].Range.InsertParagraphBefore();

    richTextControl2 = this.Controls.AddRichTextContentControl(this.Paragraphs[1].Range,
        "richTextControl2");
    richTextControl2.PlaceholderText = "Enter your first name";
}

Dim richTextControl2 As Microsoft.Office.Tools.Word.RichTextContentControl

Private Sub AddRichTextControlAtRange()
    Me.Paragraphs(1).Range.InsertParagraphBefore()
    richTextControl2 = Me.Controls.AddRichTextContentControl(Me.Paragraphs(1).Range, _
        "richTextControl2")
    richTextControl2.PlaceholderText = "Enter your first name"
End Sub

To add a content control that is based on a native content control

The following code example uses the AddRichTextContentControl method to create a new RichTextContentControl for every native rich text control that is in the document. To run this code, add the code to the ThisDocument class in your project, and call the CreateRichTextControlsFromNativeControls method from the ThisDocument_Startup event handler.

private System.Collections.Generic.List
    <Microsoft.Office.Tools.Word.RichTextContentControl> richTextControls;

private void CreateRichTextControlsFromNativeControls()
{
    if (this.ContentControls.Count <= 0)
        return;

    richTextControls = new System.Collections.Generic.List
        <Microsoft.Office.Tools.Word.RichTextContentControl>();
    int count = 0;

    foreach (Word.ContentControl nativeControl in this.ContentControls)
    {
        if (nativeControl.Type ==
            Microsoft.Office.Interop.Word.WdContentControlType.wdContentControlRichText)
        {
            count++;
            Microsoft.Office.Tools.Word.RichTextContentControl tempControl =
                this.Controls.AddRichTextContentControl(nativeControl,
                "VSTORichTextControl" + count.ToString());
            richTextControls.Add(tempControl);
        }
    }
}

Private richTextControls As New System.Collections.Generic.List _
        (Of Microsoft.Office.Tools.Word.RichTextContentControl)

Private Sub CreateRichTextControlsFromNativeControls()
    If Me.ContentControls.Count <= 0 Then
        Return
    End If

    Dim count As Integer = 0
    For Each nativeControl As Word.ContentControl In Me.ContentControls
        If nativeControl.Type = Word.WdContentControlType.wdContentControlRichText Then
            count += 1
            Dim tempControl As Microsoft.Office.Tools.Word.RichTextContentControl = _
                Me.Controls.AddRichTextContentControl(nativeControl, _
                "VSTORichTextContentControl" + count.ToString())
            richTextControls.Add(tempControl)
        End If
    Next nativeControl
End Sub

Add content controls at run time in a VSTO Add-in project

You can add content controls programmatically to any open document at run time by using a VSTO Add-in. To do this, generate a Document host item that is based on an open document, and then use methods of the Controls property of this host item. Each method has three overloads that you can use to add a content control in the following ways:

Add a control at the current selection.
Add a control at a specified range.
Add a control that is based on a native content control in the document.

Dynamically created content controls are not persisted in the document when the document is closed. However, a native content control remains in the document. You can recreate a content control that is based on a native content control the next time the document is opened. For more information, see Persist dynamic controls in Office documents.

For more information about generating host items in VSTO Add-in projects, see Extend Word documents and Excel workbooks in VSTO Add-ins at run time.

Note

To add a check box content control to a document, you must create a ContentControl object. For more information, see Content controls.

To add a content control at the current selection

The following code example uses the AddRichTextContentControl method to add a new RichTextContentControl to the beginning of the active document. To run this code, add the code to the ThisAddIn class in your project, and call the AddRichTextControlAtSelection method from the ThisAddIn_Startup event handler.

private Microsoft.Office.Tools.Word.RichTextContentControl richTextControl1;

private void AddRichTextControlAtSelection()
{
    Word.Document currentDocument = this.Application.ActiveDocument;
    currentDocument.Paragraphs[1].Range.InsertParagraphBefore();
    currentDocument.Paragraphs[1].Range.Select();

    Document extendedDocument = Globals.Factory.GetVstoObject(currentDocument);

    richTextControl1 = extendedDocument.Controls.AddRichTextContentControl("richTextControl1");
    richTextControl1.PlaceholderText = "Enter your first name";
}

Dim richTextControl1 As Microsoft.Office.Tools.Word.RichTextContentControl

Private Sub AddRichTextControlAtSelection()
    Dim currentDocument As Word.Document = Me.Application.ActiveDocument
    currentDocument.Paragraphs(1).Range.InsertParagraphBefore()
    currentDocument.Paragraphs(1).Range.Select()

    Dim extendedDocument As Document = Globals.Factory.GetVstoObject(currentDocument)


    richTextControl1 = extendedDocument.Controls.AddRichTextContentControl("richTextControl1")
    richTextControl1.PlaceholderText = "Enter your first name"
End Sub

To add a content control at a specified range

The following code example uses the AddRichTextContentControl method to add a new RichTextContentControl to the beginning of the active document. To run this code, add the code to the ThisAddIn class in your project, and call the AddRichTextControlAtRange method from the ThisAddIn_Startup event handler.

private Microsoft.Office.Tools.Word.RichTextContentControl richTextControl2;

private void AddRichTextControlAtRange()
{
    Word.Document currentDocument = this.Application.ActiveDocument;
    currentDocument.Paragraphs[1].Range.InsertParagraphBefore();

    Document extendedDocument = Globals.Factory.GetVstoObject(currentDocument);

    richTextControl2 = extendedDocument.Controls.AddRichTextContentControl(
        currentDocument.Paragraphs[1].Range, "richTextControl2");
    richTextControl2.PlaceholderText = "Enter your first name";
}

Dim richTextControl2 As Microsoft.Office.Tools.Word.RichTextContentControl

Private Sub AddRichTextControlAtRange()
    Dim currentDocument As Word.Document = Me.Application.ActiveDocument
    currentDocument.Paragraphs(1).Range.InsertParagraphBefore()

    Dim extendedDocument As Document = Globals.Factory.GetVstoObject(currentDocument)

    richTextControl2 = extendedDocument.Controls.AddRichTextContentControl( _
        extendedDocument.Paragraphs(1).Range, "richTextControl2")
    richTextControl2.PlaceholderText = "Enter your first name"
End Sub

To add a content control that is based on a native content control

The following code example uses the AddRichTextContentControl method to create a new RichTextContentControl for every native rich text control that is in a document, after the document is opened. To run this code, add the code to the ThisAddIn class in your project.

private System.Collections.Generic.List
    <Microsoft.Office.Tools.Word.RichTextContentControl> richTextControls;

private void Application_DocumentOpen(Microsoft.Office.Interop.Word.Document Doc)
{
    if (Doc.ContentControls.Count > 0)
    {
        Document extendedDocument = Globals.Factory.GetVstoObject(Doc);

        richTextControls = new System.Collections.Generic.List
            <Microsoft.Office.Tools.Word.RichTextContentControl>();
        int count = 0;

        foreach (Word.ContentControl nativeControl in Doc.ContentControls)
        {
            if (nativeControl.Type ==
                Microsoft.Office.Interop.Word.WdContentControlType.wdContentControlRichText)
            {
                count++;
                Microsoft.Office.Tools.Word.RichTextContentControl tempControl =
                    extendedDocument.Controls.AddRichTextContentControl(nativeControl,
                    "VSTORichTextControl" + count.ToString());
                richTextControls.Add(tempControl);
            }
        }
    }
}

Private richTextControls As New System.Collections.Generic.List _
    (Of Microsoft.Office.Tools.Word.RichTextContentControl)

Private Sub Application_DocumentOpen(ByVal Doc As Microsoft.Office.Interop.Word.Document) _
    Handles Application.DocumentOpen

    If Doc.ContentControls.Count > 0 Then

        Dim extendedDocument As Document = Globals.Factory.GetVstoObject(Doc)

        Dim count As Integer = 0
        For Each nativeControl As Word.ContentControl In Doc.ContentControls
            If nativeControl.Type = Word.WdContentControlType.wdContentControlRichText Then
                count += 1
                Dim tempControl As Microsoft.Office.Tools.Word.RichTextContentControl = _
                    extendedDocument.Controls.AddRichTextContentControl(nativeControl, _
                    "VSTORichTextContentControl" + count.ToString())
                richTextControls.Add(tempControl)
            End If
        Next nativeControl
    End If
End Sub

For C#, you must also attach the Application_DocumentOpen event handler to the DocumentOpen event.

this.Application.DocumentOpen +=
    new Word.ApplicationEvents4_DocumentOpenEventHandler(Application_DocumentOpen);

Share via

Add Content controls to Word documents

Add Content controls at design time

To add a content control to a document by using the Toolbox

To add a content control to a document in Word

Add content controls at run time in a document-level project

To add a content control at the current selection

To add a content control at a specified range

To add a content control that is based on a native content control

Add content controls at run time in a VSTO Add-in project

To add a content control at the current selection

To add a content control at a specified range

To add a content control that is based on a native content control

Feedback

Additional resources

Share via

Add Content controls to Word documents

Add Content controls at design time

To add a content control to a document by using the Toolbox

To add a content control to a document in Word

Add content controls at run time in a document-level project

To add a content control at the current selection

To add a content control at a specified range

To add a content control that is based on a native content control

Add content controls at run time in a VSTO Add-in project

To add a content control at the current selection

To add a content control at a specified range

To add a content control that is based on a native content control

Related content

Feedback

Additional resources