Intro

A multi-input field allows users to enter and manage multiple values displayed as tokens within a single input area.

Each value is represented as a token for easy review and removal. To help users select valid entries, you can enable features such as suggestions (for autocomplete) and the value help option (for opening a selection dialog).

Multi input

When to Use

2
do
false

Use the multi-input field if:

  • You want the user to select multiple ranges (with the value help option and the value help dialog).
  • You expect the dataset to grow significantly over time (for example, beyond 200 values).
  • You need to provide the value help option to help users select or search multiple business objects.
  • You want to enable users to add custom values.
dont
false

Don’t 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. Use the multi-combo box instead.
information
For more information on which selection control to choose, see the selection control overview.

Anatomy

  1. Tokens: Display the individual values selected by the user.
  2. n More: Shows if more tokens are available.
  3. Input field: The container where tokens are displayed and where users can type to add new values.
  4. Value help icon: Opens a value help dialog (a selection popup) where users can search for and select valid entries.

Anatomy of the multi input

Types

With Tokens

Predefined Tokens Only

If the text entered doesn’t match a predefined value, no token is created. The text remains as plain input until the user selects a valid value from the list or types text that matches one.

Multi input with predefined tokens

Token Creation from Custom Input

Users can type text that isn’t in the predefined list and create a token from this custom input.

Creating a token from custom input

Using the Value Help Icon

You can add a value help icon to the multi-input field to open a selection dialog, allowing users to choose from a predefined list of options. The dialog must be implemented separately.

Multi-input field with a value help icon for selecting predefined values.

States

Interaction State

The multi-input field has the following interaction states:

A. Regular: Default appearance when inactive.

B. Hover: Appearance when the cursor is over the field.

C. Active: Appearance when the field is selected or in focus.

D. Read only: Appearance when values cannot be edited.

E. Disabled: Appearance when the field is inactive and cannot be used.

Multi-input field displayed and styled in all interaction states.

Value State

The multi-input field can display different value states to indicate validation or status messages. These states provide visual feedback to the user.

A. None: Default state with no validation or status indication.

B. Negative: Indicates an error or invalid input (e.g., missing or incorrect data).

C. Critical: Highlights a warning or something that may require attention but isn’t an error.

D. Positive: Confirms a successful action or valid input.

E. Information: Provides additional information or guidance without a warning.

Multi-input field displayed and styled in all value states.

When an error, warning, or information value state is displayed, the details can be provided as text or formatted text. The text is shown when the corresponding control has the focus. If using a formatted text, you can include one or several links.

For details on the different states, see UI Element States.

For more information on semantic colors for value states, see How to Use Semantic Colors.

Behavior and Interaction

Adding Tokens

A token can be added using suggestions or value help. As the user types, the first suggestion item that matches the characters entered is autocompleted in the input field.

Select or Enter Values

To add values to the multi input, users can:

Select and enter values

The typed characters are matched against the beginning of the suggestion items, based on the “starts with” filter.

The autocomplete property is set by default if suggestions are available, but can also be switched off.

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 the same value once. The multi input displays an error if the same token is selected twice.

hint
  • The suggestions dropdown can be wider than the input field itself, but not wider than the current browser window (property: maxSuggestionWidth).
  • Values that are entered can also be tokenized when the user presses ENTER. The app development team can perform a custom validation of the entered data and decide whether a token should be created.
warning
The typeahead input feature is not available for Android devices.
information
For information on how to manage leading and treading whitespace (blanks) when copying and pasting text into input controls, please see removing leading and trailing whitespace.

Using Value Help

You can enable the value help option to provide a more advanced dialog for finding the relevant business object. Two dialogs can be used at present:

Multi input using value help

Viewing or Adjusting Selection

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

Expanded multi-input field showing all selected tokens from the overflow.

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.

Token with truncated text and popover showing the full value.

If the last selected token is too long to fit in the input field, only part of the label is shown. When users click the input, a popover appears showing the full list of selected and available items, including the longer one.

Popover showing all selected items, including a token with a long label that does not fully fit in the input field.

In the input field, users can navigate between tokens using the left or right arrow keys on a desktop, or by swiping left or right on mobile devices. A token can be selected by clicking/tapping it or by pressing Space when it is focused.

Multi-input field with a focused token (England) selected for interaction.

Removing Tokens

The user can remove tokens by pressing the Backspace or Delete button (when selected) on a desktop’s keyboard, or by clicking the :icon-declineClear icon next to each respective value.

Filtering

When the user starts typing in the input field, the list is filtered. Only items that match the character or 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 also 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 (bold) in the option list items. The highlighting works on the basis of “starts with per term”, regardless of the filtering method.

Multi-input field - default filtering, autocomplete in the input field is switched off

Copying and Pasting Data from a Spreadsheet or Text File

The multi-input field can handle paste actions containing multiple items, such as items that have been selected in a column of a spreadsheet or text file. The user simply selects a whole column in the spreadsheet, copies it, and then pastes it from the clipboard into the multi-input field. Each item is represented as a token. If a single value is copied and pasted into the field, it is shown as a text value, as further editing might be required before it is converted into a token.

Grouping

You can group the items in a suggestion list by a specific attribute and separate each group visually with a group header. This feature is also available for tabular suggestion lists.

The group headers are not interactive.

The column headers within the tabular suggestion list remain in place when the list is scrolled (“sticky” behavior). The suggestion list should have no more than 4 columns. If the columns don’t all fit on the screen or get too narrow on small screens, enable the responsive behavior to move columns into the pop-in area (property: enableTableAutoPopinMode).

Multi input with grouped suggestions

information
Due to a technical limitation, the group headers are not visible when clicking on the n More text.

Clear

You can add a :icon-decline(Clear) icon to the input field (property: showClearIcon). The icon appears as soon as the multi-input field 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-input field is wide enough to show the icon in addition to the value.

Multi-input field with token, text, and 'Clear' icon

Guidelines

  • 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.

Multi input - error state for an item that has already been selected

hint
For accessibility purposes, you can use ariaDescribedBy from the input control.

Multi-input field in the grid table in condensed mode

  • In display mode, use a text to show tokens, separated by bullet points. Provide an overflow for all texts that do not fit in one line.

  • In display mode, consider the following alternatives:

    • A bulleted list with a bullet per token text (for example, using formatted text).
    • A horizontal list with bullet separators between the individual token texts (for example, using text or 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

Responsiveness

Size S

  • Cozy mode.
  • When the user clicks the multi-input field, a new full screen dialog opens. After clicking the input field and typing, the 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.

Multi-input field (size S) on a smart phone

Size M

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

Suggestions on a tablet (size M)

Size L

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

Suggestions on a desktop device (size L)

Localization

The multi-input field supports left-to-right (LTR) and right-to-left (RTL) text directions to accommodate different language reading patterns.

In LTR mode, text and tokens are left-aligned with the value help icon on the right, while in RTL mode, they are right-aligned with the icon on the left.

Multi input in left-to-right mode (LTR)

Multi input in right-to-left mode (RTL)

Elements and Controls

Implementation

Visual Design

Elements and Controls

Implementation