Class Dropdown
A form control that lets users select a value from a list of options.
Inheritance
Implements
Inherited Members
Namespace: Unity.AppUI.UI
Assembly: Unity.AppUI.dll
Syntax
[UxmlElement]
public class Dropdown : Picker<DropdownItem, DropdownItem>, IEventHandler, IResolvedStyle, ITransform, ITransitionAnimations, IExperimentalFeatures, IVisualElementScheduler, IContextOverrideElement, IAdditionalDataHolder, IInputElement<IEnumerable<int>>, IValidatableElement<IEnumerable<int>>, INotifyValueChanged<IEnumerable<int>>, ISizeableElement, IPressableRemarks
The Dropdown component presents a list of options that users can choose from. It appears as a button that, when clicked, shows a list of selectable options in a popup menu.
Dropdowns are useful when you need to provide users with a set of predefined options while conserving screen space. They're commonly used in forms, settings panels, and configuration interfaces.
The component supports both single and multiple selection modes, making it versatile for different use cases.
For the best user experience, consider the following guidelines:
- Use Dropdown when you have 3-10 options. For fewer options, consider using Radio Buttons or Toggle Buttons. For more options, consider using a searchable ComboBox.
- Order the options in a logical way (e.g., alphabetically, numerically, or by frequency of use)
- Use clear, concise labels for options
Examples
Basic Dropdown: Creating a simple dropdown with string options
// Create a basic dropdown with string items
var dropdown = new Dropdown();
var items = new List<string> { "Option 1", "Option 2", "Option 3" };
dropdown.sourceItems = items;
// Add it to your UI
root.Add(dropdown);
Multiple Selection Dropdown: Creating a multiple selection dropdown with custom handling of selection changes
var dropdown = new Dropdown {
selectionType = PickerSelectionType.Multiple,
closeOnSelection = false,
defaultMessage = "Select options"
};
var items = new List<string> { "Red", "Green", "Blue" };
dropdown.sourceItems = items;
// Handle selection changes
dropdown.RegisterValueChangedCallback(evt => {
var selectedIndices = evt.newValue;
Debug.Log($"Selected {selectedIndices.Count()} items");
});
Custom Item Binding: Creating a dropdown with custom item binding and display
var dropdown = new Dropdown();
// Custom class for items
class ColorOption {
public string Name { get; set; }
public Color Color { get; set; }
}
var items = new List<ColorOption> {
new ColorOption { Name = "Red", Color = Color.red },
new ColorOption { Name = "Green", Color = Color.green }
};
dropdown.sourceItems = items;
dropdown.bindItem = (item, index) => {
var colorOption = items[index] as ColorOption;
item.label = colorOption.Name;
};
dropdown.bindTitle = (item, indices) => {
if (indices.Count() == 0)
item.label = "Select a color";
else
item.label = (items[indices.First()] as ColorOption).Name;
};
Constructors
Dropdown()
Default constructor.
Declaration
public Dropdown()Dropdown(IList, BindItemFunc, BindTitleFunc, int[])
Construct a Dropdown UI element with a provided dynamic collection of items.
Declaration
public Dropdown(IList items, Picker<DropdownItem, DropdownItem>.BindItemFunc bindItemFunc = null, Picker<DropdownItem, DropdownItem>.BindTitleFunc bindTitleFunc = null, int[] defaultIndices = null)Parameters
| Type | Name | Description |
|---|---|---|
| IList | items | An items collection. |
| Picker<DropdownItem, DropdownItem>.BindItemFunc | bindItemFunc | The binding function used to populate display data for each item. |
| Picker<DropdownItem, DropdownItem>.BindTitleFunc | bindTitleFunc | The binding function used to populate display data for the title. |
| int[] | defaultIndices | The selected index by default. |
Fields
ussClassName
The Dropdown main styling class.
Declaration
public const string ussClassName = "appui-dropdown"Field Value
| Type | Description |
|---|---|
| string |
Properties
bindTitle
A method that will be called to bind the title.
Declaration
[CreateProperty]
public Picker<DropdownItem, DropdownItem>.BindTitleFunc bindTitle { get; set; }Property Value
| Type | Description |
|---|---|
| Picker<DropdownItem, DropdownItem>.BindTitleFunc |
Methods
ApplyMultiSelectionMessage(LocalizedTextElement, int)
Apply the Picker localized multi selection message.
Declaration
protected virtual void ApplyMultiSelectionMessage(LocalizedTextElement element, int selectionCount)Parameters
| Type | Name | Description |
|---|---|---|
| LocalizedTextElement | element | The LocalizedTextElement to apply the message to. |
| int | selectionCount | The number of selected items. |
MakeItem()
Default delegate to create a new DropdownItem for any item.
Declaration
protected static DropdownItem MakeItem()Returns
| Type | Description |
|---|---|
| DropdownItem | A new DropdownItem. |
MakeTitle()
Default delegate to create a new DropdownItem for the title.
Declaration
protected static DropdownItem MakeTitle()Returns
| Type | Description |
|---|---|
| DropdownItem | A new DropdownItem. |