The Search

The search

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 the string maria will match against María, oren 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 searchField option.

Please note that the search works only when your options are strings or the values in the property specified by searchField are strings. If you want to search numbers for instance you'll have to transform them to strings.

The searchField property is also used when the user types over a select without searchbox that has the focus.

Prevent autofocus

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 beforeOptions component.

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 API contains searchText and lastSearchedText.

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 lastSearchedText instead of searchText. That is because searchText contains the text typed in the searchbox, and us updated as the user types, while lastSearchedText contains 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

Pass searchPlaceholder="Type your name" to show a placeholder in the search box

In the default multiple select without searchbox you can use the placeholder property 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.