Skip to main content

Input

The ui5-input component allows the user to enter and edit text or numeric values in one line.

Additionally, you can provide suggestionItems, that are displayed in a popover right under the input.

The text field can be editable or read-only (readonly property), and it can be enabled or disabled (disabled property). To visualize semantic states, such as "error" or "warning", the valueState property is provided. When the user makes changes to the text, the change event is fired, which enables you to react on any text change.

Note: If you are using the ui5-input as a single npm module, don't forget to import the InputSuggestions module from "@ui5/webcomponents/dist/features/InputSuggestions.js" to enable the suggestions functionality.

Keyboard Handling​

The ui5-input provides the following keyboard shortcuts:

  • [Escape] - Closes the suggestion list, if open. If closed or not enabled, cancels changes and reverts to the value which the Input field had when it got the focus.
  • [Enter] or [Return] - If suggestion list is open takes over the current matching item and closes it. If value state or group header is focused, does nothing.
  • [Down] - Focuses the next matching item in the suggestion list.
  • [Up] - Focuses the previous matching item in the suggestion list.
  • [Home] - If focus is in the text input, moves caret before the first character. If focus is in the list, highlights the first item and updates the input accordingly.
  • [End] - If focus is in the text input, moves caret after the last character. If focus is in the list, highlights the last item and updates the input accordingly.
  • [Page Up] - If focus is in the list, moves highlight up by page size (10 items by default). If focus is in the input, does nothing.
  • [Page Down] - If focus is in the list, moves highlight down by page size (10 items by default). If focus is in the input, does nothing.

ES6 Module Import​

import "@ui5/webcomponents/dist/Input.js";

import "@ui5/webcomponents/dist/features/InputSuggestions.js"; (optional - for input suggestions support)

Basic Sample​

Properties​

disabled​

DescriptionDefines whether the component is in disabled state.
Note: A disabled component is completely noninteractive.
Typeboolean
Defaultfalse

placeholder​

DescriptionDefines a short hint intended to aid the user with data entry when the component has no value.
Typestring
Default""

readonly​

DescriptionDefines whether the component is read-only.
Note: A read-only component is not editable, but still provides visual feedback upon user interaction.
Typeboolean
Defaultfalse

required​

DescriptionDefines whether the component is required.
Typeboolean
Defaultfalse
Since1.0.0-rc.3

noTypeahead​

DescriptionDefines whether the value will be autcompleted to match an item
Typeboolean
Defaultfalse
Since1.4.0

type​

DescriptionDefines the HTML type of the component.
Notes:
- The particular effect of this property differs depending on the browser and the current language settings, especially for type Number.
- Due to browser constraints, certain keyboard interactions may not be available for the 'Number' and 'Email' types.
- The property is mostly intended to be used with touch devices that use different soft keyboard layouts depending on the given input type.
Type"Text" | "Email" | "Number" | "Password" | "Tel" | "URL"
Default"Text"

value​

DescriptionDefines the value of the component.
Note: The property is updated upon typing.
Typestring
Default""

valueState​

DescriptionDefines the value state of the component.
Type"None" | "Success" | "Warning" | "Error" | "Information"
Default"None"

name​

DescriptionDetermines the name with which the component will be submitted in an HTML form.
Important: For the name property to have effect, you must add the following import to your project: import "@ui5/webcomponents/dist/features/InputElementsFormSupport.js";
Note: When set, a native input HTML element will be created inside the component so that it can be submitted as part of an HTML form. Do not use this property unless you need to submit a form.
Typestring
Default""

showSuggestions​

DescriptionDefines whether the component should show suggestions, if such are present.
Note: You need to import the InputSuggestions module from "@ui5/webcomponents/dist/features/InputSuggestions.js" to enable this functionality.
Typeboolean
Defaultfalse

maxlength​

DescriptionSets the maximum number of characters available in the input field.
Note: This property is not compatible with the ui5-input type InputType.Number. If the ui5-input type is set to Number, the maxlength value is ignored.
Typenumber | undefined
Defaultundefined
Since1.0.0-rc.5

accessibleName​

DescriptionDefines the accessible ARIA name of the component.
Typestring
Default""
Since1.0.0-rc.15

accessibleNameRef​

DescriptionReceives id(or many ids) of the elements that label the input.
Typestring
Default""
Since1.0.0-rc.15

showClearIcon​

DescriptionDefines whether the clear icon of the input will be shown.
Typeboolean
Defaultfalse
Since1.2.0

previewItem​

DescriptionThe suggestion item on preview.
TypeIInputSuggestionItem | null
Defaultnull
Readonlytrue

Slots​

default​

DescriptionDefines the suggestion items.
Note: The suggestions would be displayed only if the showSuggestions property is set to true.
Note: The <ui5-suggestion-item> and <ui5-suggestion-group-item> are recommended to be used as suggestion items.
Note: Importing the Input Suggestions Support feature:
import "@ui5/webcomponents/dist/features/InputSuggestions.js";
automatically imports the <ui5-suggestion-item> and <ui5-suggestion-group-item> for your convenience.
TypeArray<IInputSuggestionItem>

icon​

DescriptionDefines the icon to be displayed in the component.
TypeArray<IIcon>

valueStateMessage​

DescriptionDefines the value state message that will be displayed as pop up under the component. The value state message slot should contain only one root element.
Note: If not specified, a default text (in the respective language) will be displayed.
Note: The valueStateMessage would be displayed, when the component is in Information, Warning or Error value state.
Note: If the component has suggestionItems, the valueStateMessage would be displayed as part of the same popover, if used on desktop, or dialog - on phone.
TypeArray<HTMLElement>
Since1.0.0-rc.6

Events​

change​

DescriptionFired when the input operation has finished by pressing Enter or on focusout.
TypeCustomEvent

input​

DescriptionFired when the value of the component changes at each keystroke, and when a suggestion item has been selected.
TypeCustomEvent

suggestion-item-select​

DescriptionFired when a suggestion item, that is displayed in the suggestion popup, is selected.
TypeCustomEvent<InputSuggestionItemSelectEventDetail>
Parametersitem: HTMLElement
The selected item.

suggestion-item-preview​

DescriptionFired when the user navigates to a suggestion item via the ARROW keys, as a preview, before the final selection.
TypeCustomEvent<InputSuggestionItemPreviewEventDetail>
Parametersitem: HTMLElement
The previewed suggestion item.
targetRef: HTMLElement
The DOM ref of the suggestion item.
Since1.0.0-rc.8

Methods​

openPicker​

DescriptionManually opens the suggestions popover, assuming suggestions are enabled. Items must be preloaded for it to open.
Return typevoid
Since1.3.0

CSS Parts​

No CSS parts available for this component.

More Samples​

Clear Icon​

The Input can show a clear icon, visble when there is a value, typed by the user. When pressed, the value gets cleared.

Input with Suggestions​

The Input can show dropdown with suggestions upon user input - see the showSuggestions property for more information.

Suggestions Wrapping​

The sample demonstrates how the text of the suggestions wrap when too long.

Input and Label​

Value State Messate​

Value-help Dialog​

Custom Styling​

To some extent, the Input allows customization with pure CSS as shown in the sample.