Intro

A text input field allows users to enter and edit text or numeric values in one line. To help users enter a valid value, you can enable the autocomplete suggestion feature and the value help option.

Input

When to Use

false

Use the input field if:

The user needs to enter a short, single-line text or number.
The user needs to enter a password, URL, phone number, or email address.
The user needs to select a single item from a large amount of data (for example, more than 200 items).
The user needs to find an object by searching for more than one attribute, such as an ID, city, and customer name. Use this control in combination with the autocomplete suggestion feature and value help option. For a small set of values (for example, fewer than 20 items), consider using the select control. Otherwise, use the combo box (for 20-200 items).

dont

false

Don’t use the input field if:

The user needs to enter dates and times. In this case, use the date picker, date range selection, or date/time picker.
The user needs to enter long texts. In this case, use the text area.
The user needs to carry out a search. In this case, use the search field.
The user needs to select multiple values. In this case, use the multi-combo box (for fewer than 200 items) or the multi-input field (for more than 200 items).

information

For more information on which selection control to choose, see the selection control overview.

Anatomy

A text input field consists of the following elements:

Text: A placeholder that provides a hint or example of the expected input. It disappears when the user starts typing.
Field: A container that holds the input area.
Icon (optional): A Clear icon that removes any text entered in the field with a single click.

Anatomy of an input

Behavior and Interaction

Entering text using the autocomplete feature

Users can follow these steps to select an item using autocomplete:

1. Start typing into the input field. → 2. View and select a suggestion from the autocomplete list → 3. See the selected item filled in the field.

Autocomplete suggestions appear as the user types

Selecting an item using list options

Users can follow these steps to select an item using list options:

1. Click the value help icon to open the selection list. → 2. Choose an option from the list. → 3. See the selected option displayed in the field.

Value help list opened from the input field, with a selected option displayed in the final step

information

For information on how to manage leading and trailing white space (blanks) when copying and pasting text into input controls, see removing leading and trailing white space.

Responsiveness

In the examples below, the input field is shown in combination with the tabular autocomplete feature for different device sizes.

Note that when tabular suggestions are used, the column headers stay sticky when scrolling within the suggestion list.

Size S (Smartphones)

Cozy mode:

When the user clicks the input field, a new full screen dialog opens in which suggested items can be selected. Here, the pop-in feature of the responsive table is used.

Tabular autocomplete suggestion feature on a smartphone

Size M (Tablets)

Cozy mode:

The pop-in feature of the responsive table is used here, and defined columns are wrapped into a new line due to the limited space available.

Tabular autocomplete suggestion feature on a tablet

Size L (Desktops)

Compact mode:

The full table is shown by the suggestion feature.

Tabular autocomplete suggestion feature on a desktop

Types

The input control supports six types of data entry: text + numbers (default), email, URL, password, mask input, text and icons (see sample input types). Each type is optimized for its intended content and adjusts the keyboard layout on mobile devices to match the expected input format.

Note: Input types adjust the mobile keyboard layout but don’t automatically validate the entered data. Applications must handle validation and display error messages or feedback separately.

Data Entry

A. Text + numbers (default): Supports both letters and numbers, used for general text entry.

B. Email: Optimized for entering email addresses, displaying a keyboard with the “@” symbol on mobile devices.

C. URL: Designed for web addresses, showing a keyboard with quick access to “/” and “.com” keys on mobile devices.

D. Password: Masks the entered characters for secure password input.

E. Text + icons: Includes user-entered text with a trailing icon, such as a :icon-decline(Clear) icon, and may also include an additional icon like a dropdown arrow.

F. Mask input: Provides a predefined format (for example, phone or serial number) to guide data entry.

Input types

States

Interaction States

An input field can have the following interaction states:

Input interaction states

A. Active: Indicates the field is focused and ready for data entry.

B. Hover: Highlights the input field when the cursor moves over it.

C. Read-only: Shows the field as non-editable, typically with a grey background.

D. Disabled: Visually indicates the field is inactive and cannot be edited or interacted with.

information

For more information, see UI Element States.

Value States

An input field can have the following value states that provide feedback on entered data:

Examples of value states

A. Information: Signals neutral status or context without implying errors or warnings.

B. Positive: Confirms a valid input.

C. Critical: Highlights input that might need correction or review.

D. Negative: Highlights an error or invalid input.

information

For more guidance on when to use which state, see How to Use Semantic Colors.

Value States with Value State Message

When the field is focused, an additional message can be displayed below the field for more context or guidance.

Examples of input fields with value states and their corresponding messages

A. Information: Signals neutral status or context without implying errors or warnings.

B. Positive: Confirms valid input or successful completion.

C. Critical: Indicates a warning that may require user attention but is not an error.

D. Negative: Highlights an error or invalid input that needs to be corrected.

information

For more guidance on when to use which state, see How to Use Semantic Colors.

Properties

Required

Use this property to indicate that user input is required. Set the property for the specific input field to ensure that the asterisk is shown in front of the label.

Required input field

Placeholder

The placeholder, or input prompt, is a short hint (a word or short phrase) to help the user with data entry. A hint can be a sample value or a brief description of the expected format.

Placeholder

Description

You can provide an additional description of the input field, for example, for units or currency. The width of the input field and description is distributed equally by default. Although the default setting is 50%, you can change this with the fieldWidth property.

Input field description

Width

The width of the input field is set to 100% by default. Input fields are usually used in forms, where the width is determined by the form element or container that the input field is embedded in. Instead of defining a fixed width, we recommend working with proper layout containers, like the form, simple form, and responsive grid layout, and with the layout data property, where the width is defined by the 12-column approach.

Text Alignment

The input field offers six types of alignment for text values (API):

Begin
Center
End
Initial (default): Browser-configured alignment is used
Left
Right

Value Help

To help users find the correct value, you can enable the value help option (property: showValueHelp). By enabling this option, a small value help icon (:icon-value-help ) is displayed in the input field on the right-hand side. To give a better indication of the type of data that can be selected, you can exchange the value help icon (property: valueHelpIconSrc).

Once the value help option is enabled, the click event can be registered and one of the following displayed:

Select dialog (simple)
Value help dialog (complex)

Input field with value help icon

The values can also be pasted into the input field by copying and pasting, or dragging and dropping, if the user prefers. In this case, the values are automatically transformed into conditional expressions. For example: Copying values “1234” and “5678” leads to the token generation “=1234” and “=5678”. Additionally, these values are shown in the conditions tab of the value help dialog.

warning

Don’t use the “value help only” option (property: valueHelpOnly). This can result in inconsistencies for screen reader users.

Autocomplete Suggestions

The input control offers three different types of autocomplete suggestions: single, two-value, and tabular. By default, the width of the suggestion box is the same as the width of the input field. You can change it with the maxSuggestionWidth property.

Note: The maximum width of the suggestion box is always slightly smaller than the width of the screen or browser window (with 1 rem of free space on the left and right sides), regardless of the value you provide for maxSuggestionWidth.

The position of the suggestion box depends on the space available below the control. If there is not enough space, the suggestion box is shown above the control.

As the user types, the first suggestion item that matches the characters entered is autocompleted in the input field. The typed characters are matched against the beginning of the suggestion items, based on the “starts with” filter. 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. The user can accept the autocompleted value by pressing ENTER.

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

warning

The typeahead input feature is not available on Android devices.

Single Value with Autocomplete

The single-value autocomplete displays a list of suggestions where each option contains only one value (for example, a name or ID), aligned to the left.

Use this feature when a single attribute is sufficient for users to find and select an item.

Single-value autocomplete suggestion feature

Two Values with Autocomplete

The two-value autocomplete displays a list of suggestions where each option shows two attributes (for example, a name and an ID) instead of one. The primary value is left-aligned, while the secondary value is right-aligned.

Use this feature when users need both attributes to identify and select the correct item.

Two-value autocomplete suggestion feature

Tabular Autocomplete

This autocomplete feature displays the values in a table layout. Use the tabular autocomplete feature if you need to display more than two attributes.

For input fields in a tabular view, we recommend using a maximum of 4 columns. Focus on columns that are relevant for the use case. If there are too many columns for the available space, the width of the columns shrinks. Alternatively, you can enable the responsive behavior of the table (property: enableTableAutoPopinMode).

To use the tabular suggestion feature, use the suggestionColumns aggregation to define the columns and the correct responsive behavior for the pop-in content. Define appropriate responsive behavior for sizes S and M. For more information, see the article on the responsive table.

With the showTableSuggestionValueHelp property, you can offer a Show All Items button at the end of the suggest result list. Because the number of results in the suggest functionality is limited, this option helps the user find the relevant item via an alternative dialog:

Select dialog (simple)
Value help dialog (complex)

The width of the columns is distributed equally by default. To avoid truncation, accurately estimate the primary attribute length and set a minimum width for this column.

The column headers remain in place when the user scrolls through the suggestion list (“sticky” behavior).

Tabular autocomplete, suggestion box wider than the input field

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.

Input with grouped tabular suggestions

Accessibility

The property ariaDescribedBy links the input field to other controls to provide additional information for assistive technologies, such as screen readers. If you use this property, we recommend linking either to on-screen controls that provide additional context or to an invisible text.

Guidelines

Always provide a meaningful label for any input field, and use the least complex control (such as select instead of value help). Use more intricate controls only if the use case really requires it. Where appropriate, help users by providing mask input or placeholder texts.

Maximum Columns

For input fields in a tabular view, we recommend using a maximum of 4 columns.

Maximum Length

Limit the length of the input field. For example, if you don’t want users to enter more than 5 characters, set the maximum length to 5. The maximum permissible character length is not defined by default. If the back-end system has a limit, ensure that you set this property accordingly.

Note that this parameter is not compatible with the input type sap.m.InputType.Number. If the input type is set to Number, the value of the maxLength property is ignored.