Intro
The input component lets users enter or edit single-line text or numeric values. You can enable autocomplete suggestions and value help to make data entry faster and more accurate.
Input
Component availability
The component is available in the following libraries:
When to Use
Use the input to:
- Enter a short, single-line text or number.
- Enter a password, URL, phone number, or email address.
- Select a single item from a large amount of data (for example, more than 200 items).
- Find an object by searching for more than one attribute, such as an ID, city, and customer name. Use this component in combination with the autocomplete and suggestion features, and the value help option. For small data sets (fewer than 20 items), consider using the select component. Otherwise, use the combo box (for 20-200 items). For more information on which selection control to choose, see the selection component overview.
Don’t use the input to:
- Enter dates and times. In this case, use the date picker, date range selection, or date/time picker.
- Enter long texts. In this case, use the text area.
- 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).
- Ensure that input fields are consistently spaced and aligned to maintain a clean and organized layout.
- Design input fields with appropriate lengths to accommodate typical entries without excessive scrolling or truncation.
- Use clear, concise, and easily understandable labels for each input field to guide users. Don't replace labels with placeholders because placeholder text disappears once the user starts typing in the field.
- Utilize placeholder text within input fields to provide hints or examples of the expected input format.
- Provide real-time feedback for input validation, highlighting errors as users type instead of waiting for form submission.
- Implement suggestions and autocomplete features to help users enter information quickly and accurately.
Anatomy
An input consists of the following elements:
- Field: A container that holds the input area.
- Text: A placeholder or typed text.
- Icon (optional): An icon visualizing an available action (for example, a Clear icon to remove the typed text).
Anatomy of an input
Types
The input component supports six types: basic input, input with label, input with suggestions, input with value help, input with description, and input as a search (which is specific to SAP Web Components).
Basic input
The basic input is a field that allows the user to type in any kind of text. It does not offer any suggestions or additional actions.
Basic input
Input with label
Use an input with a label to clearly describe the expected value. Use short, descriptive label text (for example, “First Name”, “Invoice Date”). The input is often combined with the label component.
Input with label
Input with suggestions
Use an input with suggestions when users benefit from type-ahead help – when there’s a known set of likely values or searchable items that can be filtered as the user types, to speed input, reduce errors, and improve discoverability. Input fields can provide helpful suggestions that appear as the user types, using autocomplete and a dropdown list, such as when searching for products, customers, employees, tags, addresses, and so on.
Input with suggestions
For more information, see Suggestions and autocomplete.
Input with value help
Inputs can also trigger a value-help dialog to assist users in selecting the correct value. This dialog is opened via a value-help icon button displayed on the right-hand side of the input field. Use inputs with value help when users need to pick from a large or complex dataset, such as material lists for inventory, vendor lists for procurement, and so on.
Input with value-help icon
For more information, see Value help.
Input with description
An input field can include an additional description after the field that serves as contextual information, such as a unit of measurement, currency, or another descriptive reference.
Input with description
Input as a search :badge, info, large, _, SAP Web Components only:
Use the input component as a search field for free-text searches or to filter data. Global or contextual search lets users find items across lists, tables, catalogs, or site areas, for example, products or documents.
Note: The SAPUI5 Input component doesn't provide search capabilities on its own. Use the search field instead.
Input as a search field
States
Component states
The input component supports the following component states: enabled, disabled, and read-only.
A. Enabled: Indicates that the field can be used to perform an action. The input component is both enabled and editable by default, allowing the user to enter a value.
B. Disabled: Visually indicates the field is inactive and cannot be edited or interacted with. Set the component to disabled in an edit scenario to indicate that the user cannot change the component, for example, due to missing access rights or previous conditions not having been fulfilled or selected.
C. Read-only: Shows the field as non-editable and fully readable, typically with a grey background.
Input component states
For more information, see Component States.
Interaction states
B. Hover: Highlights the input field when the cursor moves over it.
C. Active: Indicates the field is focused and ready for data entry.
Input interaction states
For more information, see Interaction States.
Value states
B. Critical: Highlights input that might need correction or review.
C. Positive: Confirms a valid input.
D. Information: Signals neutral status or context without implying errors or warnings.
Input value states
For more information, see Value States.
Value states with value state message
A. Negative: Highlights an error or invalid input that needs to be corrected.
B. Critical: Indicates a warning that may require user attention but is not an error.
C. Positive: Confirms valid input or successful completion.
Note: The positive state does not display an input popover.
D. Information: Signals neutral status or context without implying errors or warnings.
Input value states with value state message
For more information on how values are validated in the input, see Form Field Validation.
Focus state
The focus state becomes active when the input field receives focus. If a keyboard is available, all interactive elements must provide a focus state.
Note: The active and focus states are identical for the input component.
Input focus state
For more information, see Focus States.
Behavior and Interaction
Activating an input field
The standard way to activate an input component is for a user to position the cursor inside the field and click.
A: The component starts in its regular, inactive state.
B: When the user moves the pointer over the field, the component displays a hover state.
C: When the user presses the left mouse button inside the field, the component activates the input and a caret appears in front of the placeholder text.
D: Upon releasing the mouse button, the component keeps the input active, and the caret and placeholder remain in the same position, ready for text entry.
Note: The placeholder text is application-specific.
Input interaction – click and caret position
Entering text using autocomplete
The autocomplete feature helps users quickly select items by suggesting matches as they type. The interaction flow is as follows:
A: The user activates the input field by clicking on it. The component responds by displaying the caret in front of any placeholder text.
B: As the user begins typing, the placeholder text disappears. Once the user enters the minimum number of characters required to trigger suggestions (for example, one character), the autocomplete list appears, and the first matching item is autocompleted. As a visual hint for the user, matched characters are highlighted (bold) in the list items.
C: To confirm the selection, the user presses Enter. The suggestion list closes, and the autocompleted text becomes regular typed text. The caret automatically moves to the end of this confirmed value.
Autocomplete suggestions appear as the user types
Selecting an item using list options
This component allows users to select an item from a dynamic list of options, similar to autocomplete. However, users manually select an item from the displayed list rather than confirming an autocompleted value.
A: The user activates the input field by clicking into it. The component then displays the caret in front of the placeholder text.
B: As the user begins typing in the input field, the component removes the placeholder text. Once the user enters the minimum number of characters required, the component automatically displays the suggestion list. When the user moves the pointer over a suggestion, the component shows its hover state.
Note: By default, this feature requires the entry of one character to trigger suggestions. For the SAPUI5 Input component, it is possible to define more than one required character to trigger suggestions. For more information, see Defining characters for triggering suggestions.
C: If the user presses and holds the left mouse button on a suggestion, the component activates the down state and moves focus to the selected item.
D: When the user releases the mouse button, the component sets the clicked item as the input value. The suggestion list closes, and the text becomes regular typed text. The caret moves to the end of the value.
Value help list opened from the input field, with a selected option displayed in the final step.
Defining characters for triggering suggestions :badge, info, large, _, SAPUI5 only:
You can define how many characters users must type before suggestions appear.
By default, suggestions and autocomplete appear after the first character is entered.
Input with suggestions – suggestion trigger
For information on how to manage leading and trailing white space (blanks) when copying and pasting text into input components, 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. For sizes S and M, use Cozy mode of the component, whereas for size L, use Compact mode. For more information, see Content Density (Cozy and Compact).
Note that when tabular suggestions are used, the column headers stay sticky when scrolling within the suggestion list.
Size S (smartphones)
When the user taps the input field, the keyboard appears, and the view switches to full screen, with the input field at the top and suggestions listed below. This utilizes the pop-in feature of the responsive table.
To select an item, a one-finger tap gesture is used. When an item is tapped, the full-screen view immediately closes, and the selected value is applied to the input field.
Tabular autocomplete suggestion feature on a smartphone
Size M (tablets)
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)
The full table is shown by the suggestion feature.
Tabular autocomplete suggestion feature on a desktop
Accessibility
SAP follows international standards, such as WCAG and WAI-ARIA, and strives to make our business solutions accessible and inclusive.
For more information, see Accessibility in SAP Fiori and the Accessibility Design Tools Handbook.
Keyboard navigation
The following keyboard combinations are supported by the SAPUI5 Input component.
Screen reader support
For additional details on screen reader support and Accessible Rich Internet Applications (ARIA), see UI5 Screen Reader Support and WAI-ARIA Authoring.
Content
This section outlines the guidelines for crafting effective and consistent content within the input component, ensuring clarity, accessibility, and a seamless user experience.
Input with Clear icon
A Clear icon can be added to the input field. It will appear as soon as the input field has a value. Clicking the Clear icon removes the value from the field. If used, make sure that the input field is wide enough to show the Clear icon in addition to the value.
A: The component is enabled and displays its regular state, including the typed text.
B: Positioning the pointer on the Clear icon changes the state to hover to both icon and input field.
C: Clicking on the Clear icon changes the state to active and removes the content from the input field.
D: Input field with removed content and in active state.
Input with “Clear” icon
Input with “Clear” icon and value help icon
Data entry
The input component supports six types of entered data: text (default), numbers, email, URL, telephone number, and password. For more information, see the 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: The entered data is not automatically validated. Applications must handle validation and display error messages or feedback separately.
A. Text (default): Supports letters, used for general text entry.
B. Number: Supports numbers, used for general entry.
C. Email: Optimized for entering email addresses, displaying a keyboard with the “@” symbol on mobile devices.
D. URL: Designed for web addresses, showing a keyboard with quick access to “/” and “.com” keys on mobile devices.
E. Telephone number: Supports numbers and some special symbols (#*+). An appropriate keyboard layout is shown on touch devices.
F. Password: Masks the entered characters for secure password input.
Input data entry types
Required input
To indicate that a particular field is mandatory and requires user input, set the “Required” indicator for its label, which displays an asterisk (*) next to the label.
If no value is provided, the input receives a negative state to also indicate that a value is required.
Required input field
Placeholder
The placeholder provides a short hint to help users enter valid data.
Avoid using placeholders instead of labels, because placeholder text disappears when users enter data and no longer indicates the field’s purpose.
For more information on how to write placeholder text, see UI Text Guidelines for SAP Fiori Apps.
Placeholder
Text alignment
The input field supports six text alignment options (API): initial, begin, center, end, left, and right.
- Initial (default): Uses the browser’s default alignment.
- Begin: Aligns text to the beginning of the field based on the reading direction (left in left-to-right languages, right in right-to-left languages).
- Center: Use sparingly, only when center alignment improves visual balance (for example, short codes or isolated labels).
- End: Aligns text to the end of the field based on the reading direction (right in left-to-right languages, left in right-to-left languages).
- Left: Use for text-based input types such as phone numbers, URLs, passwords, and email addresses, where left alignment remains standard regardless of language direction.
- Right: Use for numeric input such as amounts or decimal values, where users need to compare or add numbers easily.
Input field text alignments
Localization
The input component supports both left-to-right (LTR) and right-to-left (RTL) reading directions.
Input in left-to-right mode
Input in right-to-left mode
Features
Suggestions and autocomplete
The suggestions list and autocomplete features help users quickly scan and select relevant terms or values. Suggestions appear below the input field as soon as the user starts typing. The position of the suggestion box depends on the space available below the component. If there is not enough space, the suggestion box is shown above the component. By default, the suggestion box matches the width of the input field.
Autocomplete completes the first suggestion that starts with the entered characters. Depending on the list ordering, this may not be the top item shown.
The input component supports three suggestion types: single, two-value, and tabular (which is specific to SAPUI5).
Single-value suggestion
The single-value suggestion displays a list of suggestions where each option contains only one value (such as a name or an ID), aligned to the left.
Use this feature when a single attribute is sufficient for users to find and select an item.
Single-value suggestion feature
Two-value suggestion
The two-value suggestion displays a list of suggestions where each option shows two attributes (such as a name and an ID) instead of just 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 suggestion feature
Tabular suggestions:badge, info, large, _, SAPUI5 only:
Suggestions can be displayed in a table layout, with each row representing a suggestion and the columns visualizing different attributes. Use the tabular autocomplete feature if you need to display more than two attributes. We recommend using a maximum of 4 columns. Focus on columns that are really 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 to achieve appropriate responsive behavior for sizes S and M. For more information, see the article on the responsive table.
Tabular autocomplete, suggestion box wider than the input field
А Show All Items button can be shown at the end of the suggestion result list. Because the number of results is limited, this option helps the user find the relevant item via an alternative dialog, such as:
- 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.
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
Key and value text format :badge, info, large, _, SAPUI5 only:
For some use cases, the permitted input values are key-value pairs. Suggestions and autocomplete functions operate for both the key and the value. The display format in the input field can be configured as follows:
- Key
- KeyValue
- Value (default)
- ValueKey
Key-value pairs can use various suggestion visualizations, including single-value suggestions, two-value suggestions, and tabular suggestions.
Key and value text format feature
Width
Input width
Value help
Enable value help to let users choose the correct value from a dataset. To give a better indication of the type of data that can be selected, you can exchange the value help icon. Once the value help option is enabled, the click event can be registered and one of the following displayed:
- Value help dialog (complex)
- Select dialog (simple)
- Custom dialog
Use this option in combination with the autocomplete suggestion feature. The value help dialog should tell users what values have already been entered into an input field.
Input field with value help icon
Framework Comparison
Some behaviors differ between frameworks due to implementation specifics. The table below summarizes the differences between SAPUI5 and SAP Web Components and lists the framework-specific patterns.
[internal_only]To request one of these features for SAP Web Components, submit an InnerSource request.[/internal_only]
Related Links
Guidelines
Components
Select Dialog
Value Help Dialog
Combo Box
Select
Multi-Input Field
Date Range
Date/Time Picker
Multi-Combo Box
Dialog
How To Use SemanticColors
UI Kit (Figma)
SAP Fiori for Web UI Kit / Input