When to use

A dropdown field is a field with a button that, when clicked, opens a container that will be an OS Menu or a VisualElement menu. It is divided into areas for interactions or a list of choices, presenting the user with its contents only while the element is active.

Common dropdown fields

These are common dropdown menu options.

• Use DropdownField if you do not want to define certain list items in the code but want to allow these to be adjusted later
• Use EnumField if you know what type or category you want to define in the code to prevent this from being changed later

Custom dropdown fields

These are custom dropdown menu options that apply to a specific area in Unity.
‍

Dropdown buttons in IMGUI

When to use
Use the APIs below to instantiate a dropdown button and its menu with an OS Menu or a VisualElement (Custom) menu.

When to use

Dropdowns are used to present users with two or more related options from a set menu. Dropdowns are used for making selections and commands, where the selection or action is initiated based on the selection.

• Use toggles (aka “checkboxes”) if the options do not relate to each other
• To collect user input from a related list of items use toggles (also known as “checkboxes”)
• Limit menu items to a single line of text. If the items are longer than a single line, use toggles or radio buttons.

DropdownField

When to use DropdownField

Use DropdownField if you do not want to define certain list items in the code but want to allow these to be adjusted later.

• Can be extended to display any string,  which makes its use very flexible
• Can be customized by the user without adjusting the code
• Can be adjusted later in the development process
• Requires more input from the user who must type in the string

EnumField

When to use EnumField

Use EnumField if you know what type or category you want to define in the code to prevent this from being changed later.

• Is limited to only displaying enum values
• Is defined in the code and cannot be changed after compiling
• Can be set earlier in the development process if the values are certain to remain fixed
• Requires the user to simply define the enum that it links to

Dropdown button and its menu

• Dropdowns must always display their contents attached to their trigger element; they must clearly indicate their element of origin and may not appear over the trigger element or label so as not to obscure context
• Dropdown labels must always clearly communicate the nature and context of their contents
• Dropdowns should always contain an expander glyph to the right of their label which indicates the nature of the element

Dropdowns can be recognized by their expander glyph and on-element label, providing a clear point of interaction and purpose. Although these elements may appear similar to other components at first look, their construction and the way they display their contents is distinct

• Avoid having more than one level of sub-menus
• Use separating lines to group related actions
• Depict dropdowns with a single downward-pointing arrow

Menu positioning

Dropdown menus are positioned below their button with 1 px overlap, most commonly in Window Toolbars.

When used in vertically tighter layouts, dropdown menus open on top of the dropdown with the checked option aligning with the dropdown position.

Dropdown menus can open on top of the button, or align to the bottom of the button depending on the context

Opening

Dropdowns only open on activation, not on hover. A dropdown’s content opens below its label (unless space is unavailable for it to do) and appears as a connected container listing available items.
Once opened a dropdown will remain open until the user has made a selection or has navigated away from the element.

Closing

Dropdowns automatically close once a user has made a selection (for single-selection dropdowns), clicks on the element action trigger again, or navigates away from the element.

Overflow

When a dropdown contains more items than there is room to comfortably display the dropdown will enter into a state of “overflow”. How the overflow is displayed depends on the type of dropdown:

• Interface dropdowns
  When an interface dropdown enters the overflow state it invokes a scrollbar to allow navigation of the dropdown’s content.
• Menu dropdowns
  When a menu dropdown enters the overflow state the section of its content (which would otherwise be cut off) becomes nested into a new menu item and attached submenu.

Anatomy

A dropdown menu and its key parts

Dropdowns are made up of a button (interaction element), text label, and the dropdown menu (body).

1. Dropdown button (Interaction Element)
The interaction element consists of the live area of a dropdown when displayed in its default state; it is the unopened dropdown which functions as a header once the element is opened.
‍
The interaction element on dropdowns can be identified by the expander glyph to the right of its label, signifying that the element contains a second level of interaction within the immediate context. This volume acts as the primary point of interaction for a dropdown and will continue to display its label after opening.

2. Label
A dropdown’s label appears on the trigger element and can consist of an icon, a text string, or both. A dropdown’s label must always clearly indicate the nature of the dropdown in as few words as possible, providing immediate context to its contents.
‍
Labels should observe standard element-captilazation practices. Avoid ambiguous labels and acronyms whenever possible; labels should build from the interface’s context when possible.

3. Menu (body)
The body of a dropdown can vary widely depending on its function and the nature of its contents. The body is divided into areas for interactions or a list of choices, presenting the user with its contents only while the element is active.
‍
Once a selection is made or the user navigates away from the element the body will be closed and stowed.

Dropdown menu (body) layout

Several types of dropdown menus

The layout of a dropdown’s contents reflects its purpose.

If the dropdown is limited to choice selections its layout will be fairly simple. However, dropdowns with complex menus often require further structuring:

• Custom menu containers should have a fixed width set to the minimum width required by its contents,
• Custom menu containers should hug their content vertically, allowing the menu to change its height as its contents expand / collapse,
• Consider a fixed height when the contents of the menu is too tall for the screen space.
  Add a Scroll View to your menu when its contents exceeds the fixed height.

Interaction states

Interaction states for dropdown buttons

Dropdowns hide and show content on activation and have five primary states. 

Default

Default (inactive) state.

Hover

Mouse over on Dropdowns display tooltips after a short duration when hovered above.

Focused

Dropdowns that are being focused on follow the standard focus behavior; The element is highlighted with a blue border, with contents highlighting as each item is navigated to.

Hover focused

When the cursor is over the Focused dropdown element.

1. dropdown-background

2. dropdown-border

3. dropdown-text

Common dropdown fields

Custom dropdown fields