The default behavior
The default search box is by itself surprisingly smart. As you type it will filter the results
that contain the given string ignoring diacritic differences and capitalization. That means that
maria will match against
Søren and so on.
Also (only in single selects) this component supports searching and highlighting even when there is no searchbox or the component is focused but closed. It just works out of the box.
Try focusing the next component and typing, while it's opened and also while it's closed.
Customize the search field
The default search works great when your options are just strings but when your options are
objects you need to tell the component what field it should match against using the
Please note that the search works only when your options are strings or the values in the property
searchField are strings. If you want to search numbers for instance you'll have to
transform them to strings.
searchField property is also used when the user types over a select without searchbox that has
Sometimes you want do disable the default behavior of the search box,
where it will be focused when the dropdown opens. To achieve that you have to add the
autofocus parameter to the default
Pass a custom matcher
Sometimes the default matcher is not enough for you, for example if you need to match against several
fields or you need to perform fuzzy matching. If that is the case just pass your own matcher
function. It will receive the option and the search term and you can do whatever you feel like
inside as long as it returns
-1 if it doesn't match and a positive number if it does.
This field is also used when the user types over a select without searchbox that has the focus.
Using the search term inside the block
Is very common to need the search term from withing the block used to render each one of the options,
typically for apply a highlight some substring of the option's text. For that, the block, as
most actions in this component, receives an instance of the publicAPI as second argument. The public
There is a few things to be aware of this search term:
- Even if the default search is smart enough to transform diacritics, the term will unmodified, and therefore you need to handle terms as "João" or "María" yourself.
Likely the attribute of the public API that you want to use is
searchText. That is because
searchTextcontains the text typed in the searchbox, and us updated as the user types, while
lastSearchedTextcontains the search term that yielded the current collection of results. While in synchronous searches they are the same, in asynchronous searches they can temporality diverge while the search is ongoing. In the previous example, if the search was async and you used
searchText, the results wouldn't be updated and your highlighting wouldn't find a match.
Search box placeholder
searchPlaceholder="Type your name" to show a placeholder in the search box
placeholderproperty to have put text in the trigger.
Disable the search box
Last but not least you can disable and hide the search box from the list by passing
searchEnabled=false to the component.
This works with both the single and multiple select.