w:dropDownList (Drop-Down List Content Control)

Declares a structured document tag as a drop-down list content control, restricting user input to one of a fixed set of predefined items.

Parent elements

w:sdtPr

Child elements

w:listItem

Description

w:dropDownList classifies an SDT as a drop-down list content control. The user may only choose from the predefined w:listItem entries; free-text entry is not permitted.

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

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 stored value of the last item the user selected.

Child Elements

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

Examples

<w:sdtPr>
  <w:alias w:val="Status"/>
  <w:tag w:val="status"/>
  <w:dropDownList w:lastValue="Active">
    <w:listItem w:displayText="Choose a status..." w:value=""/>
    <w:listItem w:displayText="Active" w:value="Active"/>
    <w:listItem w:displayText="Inactive" w:value="Inactive"/>
    <w:listItem w:displayText="Pending" w:value="Pending"/>
  </w:dropDownList>
</w:sdtPr>

using DocumentFormat.OpenXml.Wordprocessing;

var dropDown = new SdtContentDropDownList(
    new ListItem { DisplayText = "Choose a status...", Value = "" },
    new ListItem { DisplayText = "Active", Value = "Active" },
    new ListItem { DisplayText = "Inactive", Value = "Inactive" },
    new ListItem { DisplayText = "Pending", Value = "Pending" }
)
{ LastValue = "Active" };

Notes

Unlike w:comboBox, w:dropDownList restricts the user to the listed items — no free-text input is allowed.
The w:sdtContent holds the display text corresponding to the currently selected w:value.
When processing or populating a drop-down programmatically, update both w:lastValue on w:dropDownList and the text inside w:sdtContent.