Use the combo box if:

• Users need to select a single item from a long list of items (minimum 13, maximum 200 entries).
• The values of the option list are secondary information and do not need to be displayed right away.

Do not use the combo box if:

• Users need to select from a list of two options, where one of the options can be implied as on and off or yes and no. Consider using a switch control instead.
• Users need to pick one item from a small set of options with up to 12 entries. Consider using the select control instead.
• Users need to pick one item from a large set of options with more than 200 entries. Consider using the input field control with a select dialog or value help dialog instead.
• You need to display more than one attribute. Consider using the input field with select dialog or value help dialog.
• Searching on multiple attributes is required. Consider using the input field with select dialog or value help dialog.
• Your use cases require that all available options should be displayed right away without any user interaction. Consider using radio buttons or a radio button group.

Size S

Size M

Size L

Title

A descriptive heading (1).

Input Field

The input field (2) displays the selected value. Users can type any character to filter the option list.

Dropdown Arrow

The dropdown menu’s arrow (3) collapses and expands the option list.

Option List

The option list (4) contains a list of values (5) that users can choose from.

Two-Column Layout

Use the combo box with a two-column layout if you need to display additional information for the selection options, such as currencies, country abbreviations, or system abbreviations.

Users can filter both columns simultaneously showing only matching entries.

Grouping

You can group the items in the suggestion list by a specific attribute and separate them visually with a group header.

The group headers are not interactive.

Clear

You can add a  (Clear) icon to the combo box (property: showClearIcon). The icon appears as soon as the combo box has a value. Clicking the Clear icon removes the value from the field.

If you offer the Clear icon, make sure that the combo box is wide enough to show the icon in addition to the value.

There are three ways to select an item from the list:

1. Select the item directly from the dropdown list.
2. Type the item into the input field.
3. Use the up and down arrows to navigate the list.

Clicking the input field places the cursor in the field (1). Clicking the arrow opens the option list (2). When the user starts typing, the list is filtered accordingly. The first item that starts with the characters entered is highlighted in the list and autocompleted in the input field (3). Up/down moves the highlight in the list and populates the value in the field (4). Selecting a value closes the list of options (5).

Autocomplete

When the first few letters are typed in the input field, the control performs autocomplete to help users to easily select one item from the option list.

Choose from Option List

The option list displays all the available items the user can choose from. The selection is always highlighted. Selecting another option from the list moves the highlight to the newly selected option.

Clicking the arrow opens the option list below the field. If there is not enough space, the list is displayed above the input field.

When the user starts typing in the input field, the option list is filtered. Only items that match the characters entered are shown in the dropdown list. The default filtering method is “starts with per term”, which matches the beginning of each word in an item’s text.

In addition, application developers can set a custom filtering method “starts with” or “contains” (method: setFilterFunction). The “starts with” approach filters only for items where the beginning of the label matches the query entered. The “Contains” approach searches the full label for a match.

As a visual hint for the user, the matched characters are highlighted in the option list items. The highlighting works on the basis of “starts with per term”, regardless of the filtering method.

If the filtered option list contains items that start with the characters entered by the user, the first matching, unselected item is autocompleted in the input field.

The width of the option list adapts to its content. The minimum width is the input field plus the dropdown arrow. The maximum width is the part of the screen furthest to the right. If the option list content requires even more width, entries become truncated.

A combo box has different styles for its different states. Here are some examples:

The combo box offers four value states:

• Error
• Warning
• Success
• Information

For error, warning, and information states, you can show an additional value state text message when the focus is on the combo box. The message can either be a plain text or a formatted text.

For more guidance on when to use which state, see How to Use Semantic Colors.