w:comboBox (Combo Box Content Control)

Declares a structured document tag as a combo box content control, providing a predefined list of items while also allowing free-text entry.

Parent elements

w:sdtPr

Child elements

w:listItem

Description

w:comboBox classifies an SDT as a combo box content control. Unlike w:dropDownList, the combo box also allows the user to type any free-form text value in addition to selecting from the predefined items.

It is defined in ECMA-376 Part 1 §17.5.2.3.

The last selected value is stored in the w:lastValue attribute. Each choice is a w:listItem child element.

Attributes

Attribute	Type	Possible Values	Description
`w:lastValue`	`xsd:string`	Any string	The value of the last item selected or typed by the user.

Child Elements

Element	Description
`w:listItem`	A selectable list entry. Attributes: `w:displayText` (shown in list) and `w:value` (stored value).

Examples

<w:sdtPr>
  <w:alias w:val="Department"/>
  <w:tag w:val="department"/>
  <w:comboBox w:lastValue="Engineering">
    <w:listItem w:displayText="Choose..." w:value=""/>
    <w:listItem w:displayText="Engineering" w:value="Engineering"/>
    <w:listItem w:displayText="Marketing" w:value="Marketing"/>
    <w:listItem w:displayText="Sales" w:value="Sales"/>
  </w:comboBox>
</w:sdtPr>

using DocumentFormat.OpenXml.Wordprocessing;

var comboBox = new SdtContentComboBox(
    new ListItem { DisplayText = "Choose...", Value = "" },
    new ListItem { DisplayText = "Engineering", Value = "Engineering" },
    new ListItem { DisplayText = "Marketing", Value = "Marketing" },
    new ListItem { DisplayText = "Sales", Value = "Sales" }
)
{ LastValue = "Engineering" };

Notes

The key difference between w:comboBox and w:dropDownList is that w:comboBox permits free-text entry; w:dropDownList is restricted to the predefined items.
A placeholder item with an empty w:value is conventionally used as the “unselected” initial state.