Intro

The multi-combo box lets users select one or more options from a predefined list. It includes an editable input for filtering and a dropdown with checkboxes for multi-selection.

Multi-combo box

When To Use

Anatomy

Multi-combo box anatomy

Components

Input Field

The input field can display a placeholder text when it’s empty, or a token if a value is selected.

Multi-combo box showing placeholder text (top) and selected tokens (bottom).

Dropdown Trigger

The dropdown button collapses and expands the dropdown list.

Multi-combo box expanded dropdown list with multiple selectable options (checkboxes)

Option List

The option list contains a list of selectable options. Clicking the label of an entry closes the option list and creates a token for the selected option. To enable multi-selection, every entry also has a checkbox. Clicking a checkbox creates a token. The option list remains open.

Multi-combo box expanded dropdown options list with selected items displayed as tokens.

Two-Column Layout

Use the multi-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.

Multi-combo box with a two-column layout

Behavior and Interaction

Select a Value

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

• Tick the checkbox (option list remains open).
• Click the label of a select option (option list is closed).
• Use the keyboard (space bar or Enter).

The user clicks the input field to place the cursor in the field.

Multi-combo box input field with focus indicator

Clicking the down arrow displays the list.

Multi-combo box dropdown expanded to show options after clicking the down arrow.

As the user types into the input field, the list is filtered accordingly.

Multi-combo box with dropdown list filtered by user-typed keywords

The arrow up and arrow down keys move the focus within the list, while the typed text remains in the input field.

Multi-combo box showing options filtered based on initial character input, with focus indicator highlighting the first input field.

Selected options are automatically entered into the input field as tokens.

Multi-combo box with dropdown filtered by initial character input (‘C’) and selected options added as tokens, with focus indicator highlighting the input field.

If the user selects items from the filtered option list by clicking the checkbox or by pressing the space bar on the keyboard, the text entered in the input field remains. The option list stays open. If the user selects items by clicking the label or by pressing Enter, the entered text is cleared, and the option list is closed.

The shift key can be used to select a range of items (shift+click marks the end of the range, shift+arrow up / shift+arrow down extends or narrows the selection range in the corresponding direction. Ctrl+A selects or deselects all items.

If selecting all items is a common use case, you can also show a Select All checkbox at the top of the list (property: showSelectAll).

'Select All' check box (optional)

Input Field

Any character in the input field acts as a filter for the option list. The input field only allows users to type text that matches the items in the list. If the user tries to enter character combinations that are not in the option list, visual feedback is provided to indicate that the combination of characters is invalid, while the input field suppresses the characters entered.

Choose from Option List

The option list displays all the available items that the user can choose from. Clicking the arrow opens the option list below the field. If there is not enough space to display the dropdown list below the field, it is displayed above the field instead.

Reviewing Tokens

If tokens have been selected, and the multi-combo box is not in focus, the input field displays as many tokens as possible in the available space. If more tokens have been selected, an [n] More label indicates the number of hidden tokens. The tokens in the input field appear in the order in which they were selected.

Clicking the [n] More label opens a popover below the input field, in which all selected items are shown. The user can deselect an item by clicking its checkbox or label.

Multi-combo box - 'n More' label

If the length of the last selected token exceeds the width of the input field, a label [n] Item/s is shown when the field is not in focus.

Clicking the [n] Item/s label opens a popover below the input field, in which all selected items are shown. The user can deselect an item by clicking its checkbox or label.

Multi-combo box - 'n Items' label (Desktop)

If there is only one token in the input field and its length exceeds the width of the input field, the text is truncated. Clicking the token opens a popover below the input field, in which the full text of the token is shown.

Multi-combo box - '1 Item' case (Desktop)

Filtering the Option List

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 auto-completed in the input field.

Default filtering and auto-complete

Grouping

Option list items can be grouped. Visually, the group header is a separate line above the items it groups. It does not currently provide an interaction of its own.

Grouping

Clear

You can add а :icon-declineClear icon to the combo box (property: showClearIcon). The icon appears as soon as the combo box has non-tokenized text. Clicking the Clear icon removes the non-tokenized text from the field.

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

'Clear' icon

Behavior for Mobile Devices

The following sections describe how the multi-combo box interacts on mobile devices.

Clicking the Arrow

Clicking the arrow opens the option list in a full screen dialog (A) with a title displayed in the header (B). The Close button (C) closes the dialog and cancels any selection changes in the option list. Clicking the label of an entry (D) closes the option list and creates a token of the selected option. By selecting a checkbox (E), the option list remains open and allows multi-selection. The OK button (F) takes over the selection and closes the dialog.

Left: filter bar with multi-combo box; right: full screen multi-combo box selection

Typing

As the user types into the input field (A), the list is filtered using the default “starts with per term” approach. Pressing the button next to the input field (B) toggles the view between all options and the selected options only.

Left: option list, filtered by user input; right: selected options from the list

Input Field on Collapsed List

If items have already been selected, the input field remains functional and the tokens remain visible (A). Clicking the Remove icon ( :icon-sys-cancel) in a token removes it (B). When the user clicks the input field, the list opens in full screen (C). Clicking the input field sets the focus on it (D) and the mobile device keyboard opens (F). When the user starts typing, the list is filtered (E) using the “starts with per term” approach. The input field only lets the user type characters that match the items in the list.

Left: multi-combo box with token in the input field; right: list for selection filtered by a character

Multiple Selected Items

Not all the selected tokens can be displayed at the same time because the space is limited to the size of the input field. Swiping to the side scrolls horizontally to reveal a cropped token.

Swiping to display tokens

Copying and Pasting from a Spreadsheet or Text File

The multi-combo box supports pasting multiple items at once, for example from a spreadsheet column or text file. Users can copy an entire column and paste it directly into the field. Each valid entry from the list is then added as a token, while only recognized items are displayed.

Responsiveness

The multi-combo box is optimized for keyboard and mouse interaction.

Size S

Filter bar with multi-combo box and option list in full screen (size S)

Size M

Filter bar with multi-combo box (size M)

Styles

The following images show how the states of the multi-combo box are styled.

Input Level Styles

Drop-down Level Styles

Value States

Guidelines

Label

The multi-combo box component can be displayed with or without a label. If the field is attached to another field, you don’t need to define a second label. For more information about labels in SAP Fiori, see the label guidelines.

Placeholder

Don’t use the placeholder attribute as an alternative to a label. This is important because the placeholder text will be overwritten as soon as the form is filled out. Labels are necessary because they indicate the meaning of the form fields if the placeholders are no longer visible. Show a placeholder only if the user needs a hint about what data to enter. Don’t repeat the content of the label. A hint could be a sample value or a brief description of the expected format. For more information about how to use the placeholder, see input field.

Option List

Keep the label of an entry in the select option list as short as possible because the list uses single lines only. Values that are too long may be truncated. If you need to indicate that none of the selection options are selected, show a blank input field. Define a default selection whenever possible. The multi-combo box cannot display columns. If you want to show two values in the option list, show the leading information first, followed by the secondary information in parentheses, such as Walldorf (Germany).

Don’t disable items in the option list. If an item can’t be selected, hide it.

Sorting

The option list contains all available items that the user can choose from. Choose one of the following styles depending on how you want the content to be arranged:

Logical

Sort items into a meaningful order. Group related options together and show the most common options first followed by less common options.

Logical multi-combo box

Alphabetical

Sort currencies, names, and so on into alphabetical order. We recommend this for lists with more than eight items.

Alphabetical multi-combo box

Numeric

Sort numeric values into a sequential order with the lowest number first.

Numeric multi-combo box

Chronological

Sort time-related information into chronological order with the most recent first (if applicable).

Chronological multi-combo box

Width

You can adjust the width of the option list to some extent. The multi-combo box component is usually used in forms, where the width is determined by the form element or container in which it is embedded. Therefore, we don’t recommend defining a fixed width, but rather working with proper layout containers such as the form, simple form, or responsive grid layout, and with the layout data property, where the width is defined. If you need to restrict the width to a defined value, set the width accordingly. Keep in mind that there’s no horizontal scrolling in the option list. Entries that are too long are truncated and users won’t be able to read them. To avoid this, you can enable wrapping (property: wrapping).

Unit of Measurement

You can use the layout options of the form to add the unit of measurement (UoM) after the multi-combo box. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.

Multi-Combo Box in a Filter Scenario

The multi-combo box can serve as a filter. For example, if the multi-combo box is offered in a table toolbar, and is empty (no tokens selected), the table shows all items. If the user selects picks something in the multi-combo box, the table shows only the matching items.

Alternatives for Display Mode

If a form or table supports both display and edit mode, use the multi-combo box only in edit mode. In display mode, consider the following alternatives:

• A horizontal list with bullet separators between the individual token texts (for example, using text or formatted text).
• A bulleted list with a bullet per token text (for example, using formatted text).

If the display mode equivalent needs to be a single-line text (as required for the grid table, tree table, analytical table), provide an overflow for all texts that do not fit onto the line (for example, by adding a link, opening a popover, or using an expandable text).

Recommended display mode equivalent with overflow opened

Localization

The multi-combo box adapts to both left-to-right (LTR) and right-to-left (RTL) languages. In RTL setups, the placeholder text, tokens and dropdown options are mirrored to match the natural reading direction.

Related Links