Updated: July 16, 2024

Combo Box

ui5-combobox | v1.0

Intro

The combo box allows users to select an item from a predefined list.

It provides an editable input field for filtering the list, and a dropdown menu with a list of the available options.

If the entries are not validated by the application, users can also enter a custom value.

Combo box – live example

When to Use

Do

Use the combo box:

  • If users need to select a single item from a long list of items.
  • If the list items are secondary information and do not need to be displayed right away.
Don't

Don’t use the combo box:

  • If there are only two options to choose from. Use a switch instead.
  • If users need to select an item from a short list of items. Use the select component instead.
  • If there are more than 200 list items. Instead, consider using an input field with a select or value help dialog.

Anatomy

  1. Input field: Displays the selected value.
  2. Value/text: The content the user has entered into the field.
  3. Dropdown button: Expands and collapses the option list.
  4. Option list: Contains values from which the user can choose.
 Anatomy of a combo box
Anatomy of a combo box

Variants

List Layouts

Use the two-column layout if you need to display additional information for each option.

You can group items in the option list.

Two-column layout – live example

Grouped items

Filters

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 following filter variants are available:

Starts with per term (default): Filters for items where the beginning of any word in in the label matches the query entered.

Starts with: Filters only for items where the beginning of the label matches the query entered.

Contains: Searches the full label for a match.

‘Starts with per term’ filter variant – live example
‘Starts with’ filter variant – live example
‘Contains’ filter variant – live example

Behavior and Interaction

Choose from List

  1. Clicking the dropdown button opens the suggestion list.
  2. Selecting an item from the list enters it in the input field.

Type or Paste Text

  1. The component responds as the user types or pastes in text:
    • Suggestions are filtered based on the typed text (see Filter Variants).
    • The autocomplete feature proposes matching labels. The autocompleted part of the text is highlighted.
  2. To enter a value in the input field, the user can:
    • Press Enter to accept the autocompleted text.
    • Click an item in the suggestion list.
Combo box – live example

Handling of Incorrect Values

  • If the user pastes or types a text that doesn’t match one of the selection options, it remains in place by default.
  • If data validation is implemented, entering an incorrect text triggers an error message and the field displays in an error state.
Data validation – error state for incorrect value

Responsive Behavior

On mobile phones, the selection list is displayed as a full screen dialog.

Related Links

Implementation

  • Combo Box
    (UI5 Web Components documentation)