Input With Suggestions (note: the usage depends on the framework you are using)
<ui5-inputid="suggestions-input"show-suggestionsshow-clear-iconplaceholder="Start typing country name"></ui5-input><script>// datavarui5_database_entries=["Argentina","Bulgaria","Canada","Columbia","Croatia","Denmark",'...'];varinput=document.getElementById("suggestions-input");// listen for the input eventinput.addEventListener("input",event=>{varvalue=input.value;varsuggestionItems=[];if(value){suggestionItems=ui5_database_entries.filter(item=>{returnitem.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 inputsuggestionItems.forEach(item=>{varli=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>
This is an error message. Extra long text used as an error message.
CozyCompactCondensed
<ui5-inputid="value-state-suggestions"placeholder="Start typing country name"show-suggestionsvalue-state="Warning"></ui5-input><ui5-inputplaceholder="Choose content density"show-suggestionsvalue-state="Error"><divslot="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>
<ui5-labelclass="samples-big-margin-right"for="myInput"requiredshow-colon>Name</ui5-label><ui5-inputid="myInput"placeholder="Enter your Name"required></ui5-input><ui5-labelclass="samples-big-margin-right"for="myPassword"requiredshow-colon>Secret Code</ui5-label><ui5-inputid="myPassword"type="Password"value-state="Error"placeholder="Enter your Secret Code"required></ui5-input>
Input With Value Help Dialog
Products
Clear
<ui5-inputid="valueHelpInput"placeholder="Enter product"show-suggestions><ui5-iconid="valueHelpIcon"slot="icon"name="value-help"></ui5-icon></ui5-input><ui5-dialogid="dialog"accessible-name="Products Value Help"><divslot="header"id="dialogHeader"><divid="titleBar"><h2id="headerTitle">Products</h2><ui5-buttondesign="Transparent"id="clearButton">Clear</ui5-button></div><ui5-inputid="dialogSearchInput"placeholder="Search"><ui5-iconid="dialogSearchIcon"slot="icon"name="search"></ui5-icon></ui5-input></div><ui5-listid="itemsList"no-data-text="No data"></ui5-list><divslot="footer"id="footer"><ui5-buttondesign="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);asyncfunctionloadSuggestions(){varresponse=awaitfetch("../../../assets/data/products.json");varproducts=awaitresponse.json();varquery=valueHelpInput.value.toLowerCase();varsuggestionItems=[];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=>{varli=document.createElement("ui5-suggestion-item");li.text=item;valueHelpInput.appendChild(li);});}functionshowDialog(){dialogSearchInput.value=valueHelpInput.value;loadList();dialog.show();}functioncloseDialog(){dialog.close();}asyncfunctionloadList(){varresponse=awaitfetch("../../../assets/data/products.json");varproducts=awaitresponse.json();varquery=dialogSearchInput.value.toLowerCase();itemsList.innerHTML="";products.filter(({name})=>name.toLowerCase().indexOf(query)===0).sort((a,b)=>a.name.localeCompare(b.name)).forEach(item=>{varli=document.createElement("ui5-li");li.innerHTML=item.name;li.image=item.productPicUrl;li.description=item.productId;itemsList.appendChild(li);});}functionhandleItemClick(event){varitem=event.detail.item;valueHelpInput.setAttribute("value",item.innerHTML);dialog.close();}functionclearQuery(){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.
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 BlackHorizon High Contrast WhiteQuartz LightQuartz DarkQuartz High Contrast BlackQuartz High Contrast White