Typeahead¶

Usage¶

Typeahead is a behavior that helps users search for and select from a list of suggested options by automatically predicting and completing their search queries as they type.

This is commonly used in the search bar, filtered search, and other places where users need to input text and select options from a list.

Best practices¶

• Provide accurate and relevant suggestions.
• Avoid long lists by displaying between 5 to 10 suggestions at a time.
• When needed, provide a scroll bar to view more results beyond the initial list of suggestions.

Design¶

1. Active suggestion item, 2. Suggestion item

Code¶

The typeahead is used as a directive, so you can add it to any HTML input element.

Usage¶

import { SiTypeaheadDirective } from '@siemens/element-ng/typeahead';

@Component({
  imports: [SiTypeaheadDirective, ...]
})

Typeahead - Basic¶

This is the most basic typeahead you can get. Tokenization is disabled here as it is not needed and normally enabled by default.

Typeahead - OnFocus & Scrollable¶

In many cases you would want the typeahead to already appear when the user focusses (click or tab into it) the input field.

Additionally, you maybe only want it to display after a certain amount of time to allow the user to quickly tab through multiple input fields.

Lastly, a scrollable typeahead is the better option in many cases, especially if there are a lot of options.

Tokenization is disabled here as well as it is not needed and normally enabled by default.

Typeahead - Async¶

If you want to load the typeahead options asynchronously, that is possible as well.

Just be sure to specify if you want it to be processed (searched and sorted) because per default it is assumed that async options are pre-processed.

Additionally, here we disable the automatic selection of the first item and prevent the typeahead from being closed using escape.

Tokenization is disabled here as well as it is not needed and normally enabled by default.

Typeahead - Tokenized¶

The typeahead tokenizes the input/search by default by splitting it on whitespace characters. Using the typeaheadMatchAllTokens input you can customize the search behavior.

Here it is left as the default separately, which means all the tokens need to have been found at least once where they don't overlap another token.

The options are as follows:

• no does not require all of the tokens to match.
• once requires all of the tokens to be found at least once.
• separately requires all of the tokens to be found at least once where there is not an overlapping different result. (default)
• independently requires all of the tokens to be found at least once where there is not an overlapping or adjacent different result. (independently also slightly changes sorting behavior in the same way.)

Typeahead - Custom¶

If you want to customize the typeahead even more by using your own item template and executing a function on select of an option, you can do that too.

Tokenization is kept enabled and typeaheadMatchAllTokens is set to once to match more results.

SiTypeaheadDirective API Documentation¶

Input Properties¶

Name	Type	Default	Description
siTypeahead ¶	Typeahead		Set the options of the typeahead. Has to be either an Array or an Observable of an Array of options (string or object)
typeaheadAutocompleteListLabel ¶	TranslatableString	$localize`:@@SI_TYPEAHEAD.AUTOCOMPLETE_LIST_LABEL:Suggestions`	Screen reader only label for the autocomplete list.
typeaheadAutoSelectIndex ¶	number	0	Defines the index of the item which should automatically be selected.
typeaheadClearValueOnSelect ¶	boolean	false	Defines whether the host value should be cleared when a value is selected.
typeaheadCloseOnEsc ¶	boolean	true	Defines whether the typeahead can be closed using escape.
typeaheadFullWidth ¶	boolean	false	If set, the typeahead will at minium have the width of the connected input field.
typeaheadItemTemplate ¶	TemplateRef<TypeaheadOptionItemContext>		Defines an optional template to use as the typeahead match item instead of the one built in. Gets the TypeaheadOptionItemContext passed to it.
typeaheadMatchAllTokens ¶	("no" | "once" | "separately" | "independently")	'separately'	Defines whether and how to require to match with all the tokens if typeaheadTokenize is enabled. - no does not require all of the tokens to match. - once requires all of the parts to be found in the search. - separately requires all of the parts to be found in the search where there is not an overlapping different result. - independently requires all of the parts to be found in the search where there is not an overlapping or adjacent different result. ('independently' also slightly changes sorting behavior in the same way.)
typeaheadMinLength ¶	number	1	Defines the number of characters the value of the host needs to be before a typeahead is displayed. Use 0 to have it display when focussing the host (clicking or tabbing into it).
typeaheadMultiSelect ¶	boolean	false	Defines whether multiselection of typeahead is possible with checkboxes.
typeaheadOptionField ¶	string	'name'	Defines the name of the field/property the option string is in when the typeahead options are objects.
typeaheadOptionsInScrollableView ¶	number	10	If typeaheadScrollable is true , defines the number of items visible at once.
typeaheadOptionsLimit ¶	number	20	Defines the maximum number of items added into the DOM. Default is 20 and 0 means unlimited.
typeaheadProcess ¶	boolean	true	Turns on/off the processing (searching and sorting) of the typeahead options. Is used when searching and sorting is done externally.
typeaheadScrollable ¶	boolean	false	Makes the typeahead scrollable and sets its height. Uses typeaheadOptionsInScrollableView and typeaheadScrollableAdditionalHeight .
typeaheadScrollableAdditionalHeight ¶	number	13	If typeaheadScrollable is true , defines the number of additional pixels to be added the the bottom of the typeahead to show users that it is scrollable.
typeaheadSkipSortingMatches ¶	boolean	false	Skip the sorting of matches. If the value is true , the matches are sorted according to SiTypeaheadSorting .
typeaheadTokenize ¶	boolean	true	Defines whether to tokenize the search or match the whole search.
typeaheadWaitMs ¶	number	0	Defines the number of milliseconds to wait before displaying a typeahead after the host was focused or a value inputted.

Output Properties¶

Name	Type	Description
typeaheadOnFullMatch ¶	TypeaheadMatch	Emits an Event when a typeahead full match exists. A full match occurs when the entered text is equal to one of the typeahead options. The event is a TypeaheadMatch
typeaheadOnInput ¶	string	Emits an Event when the input field is changed.
typeaheadOnSelect ¶	TypeaheadMatch	Emits an Event when a typeahead match is selected. The event is a TypeaheadMatch
typeaheadOpenChange ¶	boolean	Emits whenever the typeahead overlay is opened or closed.
typeaheadClosed ¶	void	Deprecated: Use typeaheadOpenChange instead.
typeaheadOnMultiselectClose ¶	void	Deprecated: Never emits. Use typeaheadOpenChange instead.

Attributes and Methods¶

Types Documentation¶