Log-in required.

You are trying to access the internal Editor Foundations design system.
Sign-in with your Unity Google account to continue, or visit the public site.

Implementation references

Scripting API and implementation references.

UI Toolkit
IMGUI

Overview

Dropdown button and a default OS menu in dark and light themes
Dropdown button and a default OS menu

A dropdown is a clickable element of either an OS Menu or a VisualElement menu that displays multiple related action options or settings. Dropdowns qualify as both a component and interface; they act as a way of organizing choices and/or controls together to condense menus into a discrete element, displaying possible options or inputs when activated.

Besides containing direct actions, dropdowns can be used to set parameters or to change aspects of an element such as view mode. In such circumstances the dropdown contains other components or interface elements related to the parent, operating as both an organizing structure and a utility.

Guidance

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

How to use

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

Style

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

Behavior

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.

Formatting

Anatomy and layout

Anatomy
Example of a dropdown menu and its labeled parts
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
Three different examples of dropdowns from the OS Menu, Gizmos Menu and Scene Camera Menu
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

The four interaction states of a dropdown in light and dark themes
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.

Color

Dropdown button color variables
Labeled parts of a dropdown button showing color variables for backgrounds, borders and text
Labeled parts of a dropdown button showing color variables
1. dropdown-background
--unity-colors-default-background
The default background color for controls
#A5A5A5
#282828
--unity-colors-default-border
The default border color for controls
#999999
#232323
2. dropdown-border
--unity-colors-default-text
The default text color
#090909
#D2D2D2
--unity-colors-default-text-hover
The default text color when the mouse pointer hovers over the text
#090909
#BDBDBD
3. dropdown-text
--unity-colors-dropdown-background
The background color for a dropdown control
#DFDFDF
#515151

Code samples

Dropdown fields in UI Toolkit

Common dropdown fields
APIs in UI Toolkit
DropdownField
A control that allows the user to pick a choice from a list of options that can include any string
EnumField
Makes a dropdown for switching between enum values. User can only select one item on the list, to the exclusion of others
EnumFlagsField
Makes a dropdown for switching between enum flag values that are marked with the Flags attribute. User can have multiple values selected at once.  “Nothing” and “Everything” options are added to the list automatically.
PopupField
A generic popup selection field. User can only select one item on the list, with any data type.
ToolbarMenu
A dropdown menu for the toolbar
Custom dropdown fields
APIs in UI Toolkit
TagField
Same as EnumField + “Add Tags” option
MaskField
Makes a field for masks. Same as EnumFlagsField
LayerField
Same as EnumField + “Add Layers” option
LayerMaskField
Makes a field for layers as masks. Same as MaskField
APIs in IMGUI
EditorGUI.Popup
Used to create a simple dropdown OS menu which only includes a flat list of string options that can be selected
EditorGUI.Popupin toolbar
Use .toolbardropdown style when placing into a window toolbar
EditorGUI.DropdownButton
Used to create a custom dropdown menu that is more complex than an OS menu can accommodate
EditorGUI.DropdownButton in toolbar
Use .toolbardropdown style when placing into a window toolbar
ToolbarDropDownToggle
A split button (dropdown + toggle) to place inside a window toolbar