Updated: July 16, 2024

SAPUI5 Version 1.118

Multi Input

ui5-multi-input | v1.0

Intro

A multi-input field allows the user to enter multiple values, which are displayed as tokens.

To help the user enter a valid value, you can enable the suggestions feature and the value help option.

Multi-input – live example

When to Use

Use the multi-input field:

To provide the value help option to help users select or search for multiple business objects.
To let users select multiple ranges (with the value help).
To enable users to add custom values.

Don't

Don’t use the multi-input field:

To choose multiple options from a large list.
If there is not enough space available on the screen.
To choose only one option from a list.

Anatomy

Tokens: Show individual selected values.
Input field: Area for displaying tokens and typing text.
Value help icon: Trigger for opening a value help dialog.

Anatomy of a multi-input field

Variants

With Tokens

Predefined Tokens Only

The user can write text in the input field that does not correspond with the predefined values in the list, but a token isn’t created and the text just appears in the input field.

Multi-Input with predefined tokens – live example

Including Token Creation

The user can write text in the input field that does not correspond with the predefined values in the list and create tokens with this text.

Create token from value entered – live example

With Value Help Icon

You can add a value help icon in the input field to trigger a separate value help dialog for selecting the values. The dialog must be implemented separately.

Basic multi-input field with value help icon

Behavior and Interaction

Select/Enter Values

To add values to the multi-input field, users can:

Start typing and select a value from the dropdown list. The selected values appear as tokens.
Type a text and press Enter to add a new value. This creates a new token with the typed text.

If there isn’t enough space to display all the tokens, an overflow button appears (n More, or n Items).

The user can only enter a value once. The multi-input field displays an error if the same token is selected twice.

Empty multi-input field – live example

View/Adjust Selection

If tokens are hidden in the overflow, clicking n More or n Items displays all the selected values.

To remove an item from the selection, users can

Click the “X” icon in the token.
Focus on the token to select it and use the keyboard delete key to remove the token.

Multi-combo box with multiple tokens – live example

Globalization and Localization

The multi-input field supports left-to-right (LTR) and right-to-left (RTL) reading directions.