ComboBox

A ComboBox is a text field with an arrow button that shows a list of choices. Typed text filters the list. The value is the text: a choice, or with allow-free-text (the default) any text.

<UIToolbox.ComboBox label="Size" placeholder="Type or pick a size"
    choices="Small,Medium,Large,Extra Large" />
<UIToolbox.ComboBox label="Quality" choices="Low,Medium,High,Ultra" allow-free-text="false" />
<UIToolbox.ComboBox label="Difficulty" choices="Easy,Normal,Hard" editable="false" />

var font = new ComboBox("Font")
{
    Items = new List<ChoiceItem>
    {
        new("Arial", "Sans", group: "Sans serif"),
        new("Georgia", "Serif", group: "Serif"),
        new("Courier", "Mono", group: "Monospace", enabled: false)
    }
};
font.value = "Georgia";
font.RegisterValueChangedCallback(evt => Debug.Log($"{evt.newValue} ({font.SelectedIndex})"));

Member	Description
`value`	The text. A `ChangeEvent<string>` comes at a pick, at Enter and when the focus leaves the field, not at each typed letter.
`Items`	The `ChoiceItem`s in the list: icon, detail, group and enabled state, as in `SearchDropdown`.
`Choices` (`choices`)	The texts of `Items`. A set replaces `Items` with plain items.
`AllowFreeText` (`allow-free-text`)	The value can be text that is not a choice (true). When false, other text goes back to the value, and a typed choice name in any case picks that choice.
`Editable` (`editable`)	The user can type in the field (true). When false, the field is a button for the list: see below.
`Placeholder` (`placeholder`)	Text in the empty field.
`SelectedIndex`, `SelectedItem`	The choice that is the value, or -1 and null for other text. Setting -1 clears the value.
`GroupOf`, `MakeItem`, `BindItem`	Group headers and custom rows, as in `SearchDropdown`.
`IsOpen`, `Open()`, `Close()`, `Toggle()`, `FilteredItems`	The popup state and the choices it shows.

The arrow button and F4 open the list with every choice and the value highlighted. Alt+Down also opens it.
Typing opens the list and filters it by substring. Up and Down move the highlight, Enter picks it, and Escape drops the typed text.
While the list is closed, Up and Down step the value to the previous or next enabled choice. With a gamepad, the D-pad at the first or last choice moves the focus on.
The gamepad submit button opens the list and picks the highlighted choice. The cancel button closes it.
The popup is a ChoiceList with the width of the field.

A combo box that takes no typing

Set editable="false" for a field that only picks from the list.

A click anywhere on the field opens the list. A second click closes it.
The field shows no caret, and the text cannot be changed or selected with the mouse.
Enter, Space, F4, Alt+Down and the gamepad submit button open the list. Up and Down step the value while the list is closed.
A typed letter goes to the next enabled choice that starts with it. The same letter again goes to the next one. While the list is closed, this sets the value; while it is open, it moves the highlight.
The value is always a choice, or the text that your code set. AllowFreeText has no effect.

Which field to use

Field	Use it when
Unity `DropdownField`	The list is short and has plain texts. Its menu is Unity's own; in a workspace it takes the theme colors.
`ComboBox` with `editable="false"`	The list is fixed, and the rows need an icon, a detail text, a group or a disabled state, or the list must look like the other toolbox lists.
`ComboBox` (editable)	The list is long and the user filters it by typing, or the value can be a new text.

For a search in a very long list, or for more than one choice, use a SearchDropdown.

Styling

The rules are in Assets/UIToolbox/Runtime/Resources/UIToolbox/Styles/Controls.uss.

Class	Element
`tb-combo-box`	The field. Its input is a row with the text field and the arrow.
`tb-combo-box--not-editable`	A field with `Editable` off, with the look of a `DropdownField`: the arrow is in the box, the caret and the selection are see-through, and the text has a hover color.
`tb-combo-box__text`	The text field. It takes the free width.
`tb-combo-box__arrow`	The arrow button on the right: 18 px wide, `--tb-color-surface-alt`, with hover and active states.
`tb-combo-box__popup`	The list under the field, with `tb-choice-list` (see SearchDropdown). It has the width of the field.

#ComboBox

#A combo box that takes no typing

#Which field to use

#Styling

ComboBox

A combo box that takes no typing

Which field to use

Styling