DropdownField

A DropdownField lets users choose a value from a list. When clicking on the control, it opens a drawer that presents multiple options, allowing users to select one. If you want to always display all the choices, use RadioButtonGroup.

Note: To align an element with other fields in an InspectorA Unity window that displays information about the currently selected GameObject, asset or project settings, allowing you to inspect and edit the values. More info
See in Glossary window, simply apply the .unity-base-field__aligned USS class to it. For more information, refer to BaseField.

Create a DropdownField

You can create a DropdownField with UI Builder, UXML, or C#.

UI Builder

To add options for a DropdownField in UI Builder, in the Inspector panel of the DropdownField, set the options in the Choices field.

To set the default value, in the Inspector of the DropdownField, enter the numbering sequence of the option in Index, starting at 0.

C#

The following C# example create a DropdownField with three options. The DropdownField selects the first option by default but you can change the default value by setting the index property.

var dropdown = new DropdownField(new List<string> { "Option 1", "Option 2", "Option 3" }, 0);

// Add another option.
dropdown.choices.Add("Option 4");

// To return int value instead of string.
dropdown.index = 1; // Option 2
dropdown.value = "Option 3"; // Set to an existing value
// Assert that the index is set correctly.
Assert.IsTrue(dropdown.index == 2);

// Register to the value changed callback.
dropdown.RegisterValueChangedCallback(evt => Debug.Log(evt.newValue));

// Style the dropdown.
dropdown.style.width = 200;
dropdown.style.height = 50;

The UI looks like this:

Change styles for a DropdownField

You can override the default Panel Settings fields in a USS file to change the styles of a DropdownField:

1. In the Hierarchy window, select your UI Document (.uxml).
2. Set Panel Settings as your Panel Settings asset. If you don’t have an existing Panel Settings asset, follow the instructions in the dialog to create one.
3. In your Panel Settings asset, assign a Theme Style Sheet.
4. In the Project window, select your TSS file.
5. Go to Style Sheets and select the Add (+) button.
6. Set your Style Sheet as your USS file.

Examples

The following UXML example creates a DropdownField:

<UXML xmlns="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements">
    <DropdownField label="UXML Field" name="the-uxml-field" />
</UXML>

The following C# example illustrates some of the customizable functionalities of the DropdownField:

/// <sample>
// You can provide the list of choices by code, or by comma separated values in UXML
// <DropdownField .... choices="Option 1,Option 2,Option 3" .... />
var choices = new List<string> { "Option 1", "Option 2", "Option 3" };

// Get a reference to the dropdown field from UXML and assign a value to it.
var uxmlField = container.Q<DropdownField>("the-uxml-field");
uxmlField.choices = choices;
uxmlField.value = choices[0];

// Create a new dropdown with the same choices, disable it, and give it a style class.
var csharpField = new DropdownField("C# Field", choices, 0);
csharpField.SetEnabled(false);
csharpField.AddToClassList("some-styled-field");
container.Add(csharpField);

// Mirror the value of the UXML field into the C# field.
uxmlField.RegisterCallback<ChangeEvent<string>>((evt) =>
{
    csharpField.value = evt.newValue;
});
/// </sample>

To try this example live in Unity, go to Window > UI Toolkit > Samples.

C# base class and namespace

C# class: DropdownField
Namespace: UnityEngine.UIElements
Base class: PopupField_1

Inherited UXML attributes

This element inherits the following attributes from its base class:

This element also inherits the following attributes from VisualElement:

USS classes

The following table lists all the C# public property names and their related USS selector.

You can also use the Matching Selectors section in the Inspector or the UI Toolkit Debugger to see which USS selectors affect the components of the VisualElement at every level of its hierarchy.

Additional resources

• RadioButtonGroup