A multi-input field allows the user to enter multiple values, which are displayed as tokens. These can be displayed in single and multiline mode. To help the user enter a valid value, you can enable the autocomplete suggestions feature and the value help option.

Usage

Use the multi-input field if:

• You want the user to select multiple ranges (with the value help option and the value help dialog).
• The dataset to choose from is expected to increase over time (for example, to more than 200 values).
• You need to provide the value help option to help users select or search multiple business objects.

Do not use the multi-input field if:

• You want the user to select one entry only. In this case, use the input field or combo box instead.
• You want the user to select from a pre-defined set of options only. In this case, use the multi-combo box instead.

Responsiveness

In the examples below, the autocomplete feature is shown in different sizes for single and multiline modes.

Single Line Mode (Default)

Size S (Smartphones)

• Cozy mode.
• When the user taps the multi-input field, a new full-screen dialog opens in which the autocomplete suggestions can be selected. When the user makes a selection, the dialog closes and the token is displayed.
• The user can review the tokens by swiping them to the left or right.

Size M (Tablets)

• Cozy mode.
• The user can review tokens by swiping them to the left or right.
• The autocomplete suggestions appear below or above the multi-input field.

Size L (Desktops)

• Compact mode.
• The user can review tokens by pressing the right or left arrows on the keyboard.
• The autocomplete suggestions appear below or above the multi-input field.

Types

The input types of the multi-input are identical to those of the input field. For more information, see input field.

Behavior and Interaction

Single Line Mode

Adding a Token

Reviewing Tokens

Deleting Tokens

The user can delete tokens by pressing the Backspace or Del button (when selected) on a desktop’s keyboard, or by tapping the Delete icon on a mobile device.

Using Value Help

Multiline Mode

Single line mode is active by default, so to activate multiline mode, you need to enable it (property: enableMultiLineMode).

Adding a Token

The user can add a token via autocomplete suggestions or value help. The token is created by selecting an item from the autocomplete box. The input is ready for the next entry. Tokens are placed next to each other. If there is not enough space on one line, the control expands.

Reviewing Tokens

When the multi-input field is not focused, it is shown in collapsed mode. The token that was entered last is displayed. If there is more than one token, the number of hidden tokens is shown next to the last token.

When tokens are entered into the multi-input field, the control expands to show all tokens. On screen size S, a new dialog is opened to review the tokens.

Copying and Pasting Data from a Spreadsheet or Text File

The multi-input control can handle paste actions containing, for example, multiple items that have been selected in a column of a spreadsheet or text file. The user simply selects a whole column in the spreadsheet and copies it. When items are entered into the multi-input field, the user just pastes them from the clipboard and each item is represented as a token.

Guidelines

• Use the multiline mode instead of the single line mode (default). This provides greater flexibility for displaying multiple tokens.
• Give the control a width that is appropriate for the range of values that are going to be entered. Try to avoid setting a fixed width on this control. Instead, embed it in a proper layout (such as a form, simple form, or grid layout) and work with the layout data property.
• Provide meaningful labels for all input fields. Do not use the placeholder as a replacement for the label. The placeholder should only provide an additional hint.
• The multi-input field can currently contain tokens and one free text value. If you allow only validated values, display an error or warning when the user tries to leave the field to indicate that the value entered is invalid, or remove the value.
• If users try to select an item that has been selected before, we recommend setting an error state and providing a meaningful message.

• You can use the layout options of the form to can add the unit of measurement (UoM) after the multi-input control. 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.

Properties

Since the multi-input field is derived from the input field, refer to the properties in the input field article.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.