intellij-sdk-code-samples/topics/ui/controls/drop_down.md

Drop-Down List

UI guidelines on using drop-down lists.

Implementation: ComboBox

A drop-down list is a type of control that shows a list of choices when clicking on it and allows selecting one option.

{width=706}

When to use

Single option

Use when a single option should be selected.

{width="706"}

Choices are objects or states

The possible choices are objects or states.

{width=706}

More than four options

The number of options is more than four.

{width="706"}

Space is limited

The screen space is limited, so there is not enough room for radio buttons.

{width="706"}

Default value is the most used

The default value is recommended for most users. A drop-down is a good way to hide unpopular alternatives.

{width=706}

Combined controls

If a control combines various UI elements as one setting, use a drop-down even if there are four options or fewer:

{width=706}

When not to use

Four or less options

If there are four options or fewer, use radio buttons.

Correct

Incorrect

Multiple selection

If multiple selections are possible, use checkboxes.

Correct

Incorrect

List of actions

If there is a list of actions, use a menu or a split button.

Correct

Incorrect

Adding values

If users may need to enter a value not currently in the list, use a combo box.

Correct

Incorrect

On a toolbar

If a drop-down appears on a toolbar, use toolbar drop-down instead.

Correct

Incorrect

How to use

Label

Follow the rules for the input field.

{width=706}

Default value

Select the most likely or the safest value by default. For example, the safest value is Ask, the behavior will not be unexpected to users:

{width=706}

Do not use an empty value as the default value. If no values are added to a drop-down yet, replace it with a button to add values.

Correct

Incorrect

Menu items

Capitalization

Use sentence-style capitalization for each menu item.

Correct

Incorrect

No repeated words in items

Avoid repeating words in drop-down list items. Move repeating words to the label or after the drop-down.

Correct

Incorrect

Sorting items

Sort items in one of the following orders:

	Logical order, for example, in a spatial relationship.
	Alphabetical or numeric order if the options are equivalent to make it easier to find items.
	Place the most common options first. If there are more than 10 options, separate the most popular options with a line.

Grouping

Group related options, use a separator and add group headers if possible.

{width=706}

Actions related to a drop-down

If there are actions related to the drop-down, put them under the gear icon on the right:

{width=706}

Meta-options

Enclose meta-options in pointy brackets and place meta-options at the beginning or at the end if they are secondary.

{width=706}

Do not assign special meanings to numeric or string values, use meta-options instead. It can be unclear that either 0 or an empty string are used to disable an option.

Correct

Incorrect

'None' in simple layouts

Replace the <None> option with a checkbox if it doesn't make the layout more complex.

Correct

Incorrect

Use previews in the list

	Preview list items with images or icons if they are associated with well-known icons.
	Use font formatting for a list of fonts. It will help users make a choice.

Default and changed values

Use a blue font for values changed from the default. Use a secondary text to mark an option as default.

Submenus are not supported

Submenus are not supported for the drop-down list. Use a tree view instead

{width=706}

Built-in behaviour

Opening the menu

A drop-down menu opens on clicking the drop-down button anywhere or pressing the Down key when the drop-down is focused.

The menu opens down by default. If there is not enough space, the menu opens up.

Selected value

When the menu opens, the default option (displayed when the menu is closed) is selected.

Moving the selection

Selection in the menu is moved by pressing Up and Down arrows when an item is hovered. Selection is moved as well when hovering the cursor over an item but it doesn't update the value.

Closing the menu

The menu remains opened until the user selects an item, clicks outside the menu, presses the Esc key or switches to another app.

Single-click activation

Single-click activation using a mouse should be allowed:

1. Clicking on a drop-down.
2. The drop-down opens, selecting an item by hovering.
3. When releasing the mouse button, the drop-down closes with the new item selected.

How to layout

Follow the labeled input controls guideline.