Input

@ui5/webcomponents
<ui5-input>

Basic Input

<ui5-input show-clear-icon value="Input"></ui5-input>
<ui5-input readonly value="readonly Input"></ui5-input>
<ui5-input disabled value="Disabled Input"></ui5-input>
	

Input With Suggestions (note: the usage depends on the framework you are using)

<ui5-input id="suggestions-input" show-suggestions show-clear-icon placeholder="Start typing country name"></ui5-input>

<script>
	// data
	var ui5_database_entries = ["Argentina", "Bulgaria", "Canada", "Columbia", "Croatia", "Denmark", '...'];

	var input = document.getElementById("suggestions-input");
	
	// listen for the input event
	input.addEventListener("input", event => {
		var value = input.value;
		var suggestionItems = [];

		if (value) {
			suggestionItems = ui5_database_entries.filter(item => {
				return item.toUpperCase().indexOf(value.toUpperCase()) === 0;
			});
		}

		// remove the previous suggestions
		[].slice.call(input.children).forEach(child => {
			input.removeChild(child);
		});

		// add the new suggestions according to the  user input
		suggestionItems.forEach(item => {
			var li = document.createElement("ui5-suggestion-item");
			li.icon = "world";
			li.additionalText = "explore";
			li.additionalTextState = "Success";
			li.description = "travel the world";
			li.text = item;
			input.appendChild(li);
		});
	});
</script>
	

Input with Value State

<ui5-input value="Success" value-state="Success"></ui5-input>
<ui5-input value="Warning" value-state="Warning"></ui5-input>
<ui5-input value="Error" value-state="Error"></ui5-input>
<ui5-input value="Information" value-state="Information"></ui5-input>
	

Input with Suggestions and Value State message

This is an error message. Extra long text used as an error message.
Cozy Compact Condensed
<ui5-input id="value-state-suggestions" placeholder="Start typing country name" show-suggestions value-state="Warning">
</ui5-input>

<ui5-input placeholder="Choose content density" show-suggestions value-state="Error">
	<div slot="valueStateMessage">This is an error message. Extra long text used as an error message.</div>
	<ui5-li>Cozy</ui5-li>
	<ui5-li>Compact</ui5-li>
	<ui5-li>Condensed</ui5-li>
</ui5-input>
	

Input as Search Field

<style>
	.inputIcon {
		background: #fafafa;
		color: #0a6ed1;
		cursor: pointer;
	}
	.inputIcon:hover{
		background: rgba(224,224,224,0.5)
	}
</style>

<ui5-input id="searchInput" placeholder="Enter search criteria ..." style="width: 100%">
	<ui5-icon id="searchIcon" slot="icon" name="search"></ui5-icon>
</ui5-input>

<script>
	var searchCriteria = "PASTA";
	searchIcon.addEventListener("click", function(){
		alert("Look for: " + searchCriteria);
	});
	searchInput.addEventListener("change", function(e){
		searchCriteria = e.target.value;
	});
</script>
	

Input with Label

Name
Secret Code
<ui5-label class="samples-big-margin-right" for="myInput" required show-colon>Name</ui5-label>
<ui5-input id="myInput" placeholder="Enter your Name" required></ui5-input>

<ui5-label class="samples-big-margin-right" for="myPassword" required show-colon>Secret Code</ui5-label>
<ui5-input id="myPassword" type="Password" value-state="Error" placeholder="Enter your Secret Code" required></ui5-input>
	

Input With Value Help Dialog

Products

Clear
<ui5-input id="valueHelpInput" placeholder="Enter product" show-suggestions>
	<ui5-icon id="valueHelpIcon" slot="icon" name="value-help"></ui5-icon>
</ui5-input>

<ui5-dialog id="dialog" accessible-name="Products Value Help">
	<div slot="header" id="dialogHeader">
		<div id="titleBar">
			<h2 id="headerTitle">Products</h2>
			<ui5-button design="Transparent" id="clearButton">Clear</ui5-button>
		</div>
		<ui5-input id="dialogSearchInput" placeholder="Search">
			<ui5-icon id="dialogSearchIcon" slot="icon" name="search"></ui5-icon>
		</ui5-input>
	</div>

	<ui5-list id="itemsList" no-data-text="No data"></ui5-list>

	<div slot="footer" id="footer">
		<ui5-button design="Transparent" id="cancelButton">Cancel</ui5-button>
	</div>
</ui5-dialog>

<script>
	valueHelpInput.addEventListener("input", loadSuggestions);
	valueHelpIcon.addEventListener("click", showDialog);
	dialogSearchInput.addEventListener("change", loadList);
	dialogSearchIcon.addEventListener("click", loadList);
	clearButton.addEventListener("click", clearQuery);
	cancelButton.addEventListener("click", closeDialog);
	itemsList.addEventListener("item-click", handleItemClick);

	async function loadSuggestions() {
		var response = await fetch("../../../assets/data/products.json");
		var products = await response.json();

		var query = valueHelpInput.value.toLowerCase();
		var suggestionItems = [];

		if (query) {
			suggestionItems = products
				.filter(({ name }) => name.toLowerCase().indexOf(query) === 0)
				.map(({ name }) => name)
				.sort((a, b) => a.localeCompare(b))
				.slice(0, 10);
		}

		[].slice.call(valueHelpInput.children, 1).forEach(item => {
			valueHelpInput.removeChild(item);
		});

		suggestionItems.forEach(item => {
			var li = document.createElement("ui5-suggestion-item");
			li.text = item;
			valueHelpInput.appendChild(li);
		});
	}

	function showDialog() {
		dialogSearchInput.value = valueHelpInput.value;
		loadList();
		dialog.show();
	}

	function closeDialog() {
		dialog.close();
	}

	async function loadList() {
		var response = await fetch("../../../assets/data/products.json");
		var products = await response.json();
		var query = dialogSearchInput.value.toLowerCase();

		itemsList.innerHTML = "";

		products
			.filter(({ name }) => name.toLowerCase().indexOf(query) === 0)
			.sort((a, b) => a.name.localeCompare(b.name))
			.forEach(item => {
				var li = document.createElement("ui5-li");
				li.innerHTML = item.name;
				li.image = item.productPicUrl;
				li.description = item.productId;

				itemsList.appendChild(li);
			});
	}

	function handleItemClick(event) {
		var item = event.detail.item;
		valueHelpInput.setAttribute("value", item.innerHTML);
		dialog.close();
	}

	function clearQuery() {
		dialogSearchInput.setAttribute("value", "");
		loadList();
	}
</script>
	

Overview

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:
  • [ESC] - 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.
  • [PAGEUP] - If focus is in the list, moves highlight up by page size (10 items by default). If focus is in the input, does nothing.
  • [PAGEDOWN] - 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)

Properties/Attributes

You can use both properties and attributes with the same effect. The name of each attribute is listed below the name of the property, if different.

Name
Type
Default Value
Description
accessibleName
accessible-name
string
Defines the accessible ARIA name of the component.
since v1.0.0-rc.15
accessibleNameRef
accessible-name-ref
string
""
Receives id(or many ids) of the elements that label the input.
since v1.0.0-rc.15
disabled
boolean
false
Defines whether the component is in disabled state.

Note: A disabled component is completely noninteractive.
maxlength
Integer
Sets 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.
since v1.0.0-rc.5
name
string
""
Determines 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.
noTypeahead
no-typeahead
boolean
false
Defines whether the value will be autcompleted to match an item
since v1.4.0
placeholder
string
""
Defines a short hint intended to aid the user with data entry when the component has no value.
previewItem (readonly)
preview-item
IInputSuggestionItem|null
The suggestion item on preview.
readonly
boolean
false
Defines whether the component is read-only.

Note: A read-only component is not editable, but still provides visual feedback upon user interaction.
required
boolean
false
Defines whether the component is required.
since v1.0.0-rc.3
showClearIcon
show-clear-icon
boolean
false
Defines whether the clear icon of the input will be shown.
since v1.2.0
showSuggestions
show-suggestions
boolean
false
Defines 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.
type
InputType
"Text"
Defines the HTML type of the component. Available options are: Text, Email, Number, Password, Tel, and URL.

Notes:
  • The particular effect of this property differs depending on the browser and the current language settings, especially for type Number.
  • The property is mostly intended to be used with touch devices that use different soft keyboard layouts depending on the given input type.
value
string
""
Defines the value of the component.

Note: The property is updated upon typing.
valueState
value-state
ValueState
"None"
Defines the value state of the component.

Available options are:
  • None
  • Error
  • Warning
  • Success
  • Information

Slots

This Element provides slot(s). This means it can display its child nodes.
Unless targeting the default slot, use the slot attribute to define the destination slot for each child.
Text, along with HTML Elements with no slot attribute, goes the the default slot.

Slot
Type
Description
default
HTMLElement [0..n]
Defines the suggestion items.

Example:

<ui5-input show-suggestions>
    <ui5-suggestion-item text="Item #1"></ui5-suggestion-item>
    <ui5-suggestion-item text="Item #2"></ui5-suggestion-item>
</ui5-input>


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.
icon
HTMLElement [0..n]
Defines the icon to be displayed in the component.
valueStateMessage
HTMLElement [0..n]
Defines the value state message that will be displayed as pop up under the component.

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.

Events

This Web Component fires semantic events upon user interaction. You can bind to these events with the standard DOM APIs, such as addEventListener.

Name
Description
change
Fired when the input operation has finished by pressing Enter or on focusout.
input
Fired when the value of the component changes at each keystroke, and when a suggestion item has been selected.
suggestion-item-preview
Fired when the user navigates to a suggestion item via the ARROW keys, as a preview, before the final selection.
since v1.0.0-rc.8
item
type: HTMLElement
description: The previewed suggestion item.
targetRef
type: HTMLElement
description: The DOM ref of the suggestion item.
suggestion-item-select
Fired when a suggestion item, that is displayed in the suggestion popup, is selected.
item
type: HTMLElement
description: The selected item.

Methods

This Web Component exposes public methods. You can invoke them directly on the Web Component instance.

Name
Description
openPicker
Manually opens the suggestions popover, assuming suggestions are enabled. Items must be preloaded for it to open.

SuggestionItem

The ui5-suggestion-item represents the suggestion item of the ui5-input.

Properties/Attributes

You can use both properties and attributes with the same effect. The name of each attribute is listed below the name of the property, if different.

Name
Type
Default Value
Description
additionalText
additional-text
string
Defines the additionalText, displayed in the end of the item.
since v1.0.0-rc.15
additionalTextState
additional-text-state
sap.ui.webc.base.types.ValueState
"None"
Defines the state of the additionalText.

Available options are: "None" (by default), "Success", "Information", "Warning" and "Error".
since v1.0.0-rc.15
description
string
Defines the description displayed right under the item text, if such is present.
icon
string
Defines the icon source URI.

Note: SAP-icons font provides numerous built-in icons. To find all the available icons, see the Icon Explorer.
iconEnd
icon-end
boolean
false
Defines whether the icon should be displayed in the beginning of the item or in the end.

Note: If image is set, the icon would be displayed after the image.
image
string
Defines the image source URI.

Note: The image would be displayed in the beginning of the item.
text
string
""
Defines the text of the component.
type
sap.ui.webc.main.types.ListItemType
"Active"
Defines the visual indication and behavior of the item. Available options are Active (by default), Inactive and Detail.

Note: When set to Active, the item will provide visual response upon press and hover, while when Inactive or Detail - will not.
since v1.0.0-rc.8

SuggestionGroupItem

The ui5-suggestion-group-item is type of suggestion item, that can be used to split the ui5-input suggestions into groups.

Properties/Attributes

You can use both properties and attributes with the same effect. The name of each attribute is listed below the name of the property, if different.

Name
Type
Default Value
Description
text
string
""
Defines the text of the ui5-suggestion-group-item.
Theme: Morning Horizon (Light) Evening Horizon (Dark) Horizon High Contrast Black Horizon High Contrast White Quartz Light Quartz Dark Quartz High Contrast Black Quartz High Contrast White
Content Density: Cozy Compact
Text Direction: LTR RTL
Apply Cancel